106:T684,Opens a Stripe Checkout session in `setup` mode: it saves a card WITHOUT charging it. This is the card-on-file flow that agent purchases and domain buys draw against later; it is not a plan purchase (see `/billing/checkout` for that). Requires `billing:manage` (owners and admins). Supply EITHER `return_url` for the embedded flow, OR both `success_url` and `cancel_url` for the hosted redirect flow. Supplying neither is a 400. `ui_mode` is optional and picks how the session is shown. Leave it out (a `null` or an empty string counts as leaving it out), or send `embedded`, for the behavior from before it existed: Stripe Embedded Checkout when `return_url` is set, and the hosted redirect when only `success_url` and `cancel_url` are. `elements` is Elements with the Checkout Sessions API: the caller renders the whole page and mounts only Stripe's Payment Element with the returned `client_secret`, so the page can wear its own theme. It needs `return_url`, which is where redirect based payment methods and the finished setup land, and the session is created on a Stripe API version of the dahlia release train (the billing guide names the exact version), so mount it with a Stripe.js of that train. The response's `ui_mode` says what was really created (`embedded`, `elements` or `hosted`): an `elements` request answers `embedded` when Stripe could not create an Elements session, so read it before mounting anything. `hosted` is only ever an answer, never a request value: a client that keeps the response's `ui_mode` must not send it back (the redirect flow is chosen by sending `success_url` and `cancel_url` without `return_url`). Any other value is a 400.107:T408,How secure sign-in sessions (the cloud browser) went in the window, overall and per DNS provider. `funnel` counts the sessions that reached each stage (started, sign-in shown, signed in, plan ready, making changes, done) with the drop from the stage before. `times` is the median and 90th percentile of the seconds from the stage before it that has a time, over the sessions that reached it; `total` is start to done for the sessions that finished. `stops` files every session that ended without finishing under one plain reason (`browser_not_started`, `left_at_sign_in`, `code_never_entered`, `provider_page_not_understood`, `provider_refused`, `timed_out`, `cancelled`, `changes_failed`, `error`). A session finished by hand counts in `done_by_hand`, a running one in `in_progress`; neither is in the funnel's done or the stops. Counts and times only: no domain, person or anything typed. Scoped to the key's workspace and `app_id` when given. At most 20000 sessions are read, newest first (`truncated`). API key; any member role.108:T425,What the edge served for one connected domain: requests by status class, bytes relayed to visitors, the origin's time to first byte (p50, p95, p99 and mean over the requests that reached it) and approximate unique visitors, as a series with totals, plus when the edge last served a request for it. `serving` says whether the domain's visitors reach the edge at all: `live` and `verifying` are served by the edge; `not_live` will be once the domain is live; `dns_only` means its records point somewhere other than the edge (it was connected for DNS only), so its traffic never passes through CustomDomain™ and there is nothing to count. Visitors are estimated from a sketch of keyed hashes of client addresses; no address is stored, and a visitor seen on two UTC days counts once on each. A tenant API key reads a domain of any application in its tenant; a widget token minted with scope `app` (or a delegated agent token) reads its own application's domains; an end user's connect-scoped widget token is refused. A delegated agent token needs `domains:read`.109:T84d,Public by design: the opaque, unguessable `token` in the path IS the credential (mirroring the OAuth callback's state-as-credential pattern), so no bearer is required. Returns the stored `prefill` so a teammate's widget can resume the flow. A share token EXPIRES 30 days after it is minted; unknown OR expired tokens are indistinguishable and both return `404`. The `widget_token` it answers reaches only the shared domains (intersected with the sharer's binding when the sharer was bound) and owns exactly what the sharer owned: the sharer's end user and the domains the sharer's own binding made its own, never the shared domains it is bound to (`createSharedFlow`). So it sets the connection the link was made for up as the end user would (the secure sign in, managed DNS, a nameserver move, the monitoring reads), and acts on a connection that names no end user only when the sharer could have (a link from a sharer that names no end user and is bound to no domain may start the secure sign in on the connection it owns, the one a call is about). A link made before the sharer was recorded (before this release), and one whose shared domains are all outside the sharer's binding, mints no `widget_token`; the first is answered `404` like an expired link, whose answer the console words as "invalid or expired, ask for a fresh link". A reconnect link is the end user's own and keeps working, except that one whose key was replaced by another, or whose connection is gone, now answers `404` too (it used to open the plain flow). A share link is a credential for that one setup, not the end user, so it never removes the domain (`403` `forbidden`, on every connection), never sets the end user's contact address (on any connection), is never offered the end user's kept keys (saved access) and is not the maker of a key as the end user: a key made at a sign in it starts is not the end user's own for saved access, and is never swapped into a key row the end user already keeps, and its sign in is never in reconnect mode (`403` `forbidden`: it cannot renew the end user's key). A reconnect link's token stays the end user.10a:Ta19,Event types to subscribe to; empty subscribes to all events, and `"*"` also matches all. Every value listed here has a producer: the enum is asserted against the emit sites in CI, so you can never subscribe to an event that cannot arrive. `connection.records.updated` / `connection.reapply.failed` / `connection.disconnected` cover the managed (async one-click) re-apply and disconnect lifecycle; `connection.disconnected` carries a `removal` object saying what happened to the DNS records. `certificate.issued` / `certificate.renewed` / `certificate.failed` follow the edge's certificate reports, and `certificate.expiring` fires 14, 7 and 3 days before an unrenewed certificate expires and when it expired; each carries a `certificate` object. `domain.record_missing` / `domain.record_restored` carry a `drift` object with the record, what public DNS shows and what was done about it. `connection.records_outdated` fires once per domain a routing change moves (saving a connect target, or `POST /v1/connections/{id}:retarget`), carrying `records.previous` and `records.current`; the domain needs the new records. `certificate.failed` fires once per failure episode, when the edge first reports that issuing or renewing the certificate failed. `secure_status` is sent only where the deployment has Secure on (`SECURE_ENABLED`), once each time a certificate's status changes. Every connection, certificate and routing event also appears on the domain's timeline (`GET /v1/connections/{id}/events`) as a row of the same kind. The `nameservers.*` events follow a nameserver migration (`POST /v1/connections/{id}/nameservers:migrate`), each with a `nameservers` object (`NameserverEventData`): `started`, `dnssec_cleared` (the registry stopped publishing the DS record), `changed` (the registrar took the new nameservers), `active` (the registry lists every one of them), `failed` (with `failure_code`), `rolled_back`, and `drifted` (an active migration's nameservers were changed away; `observed_nameservers` says to what). They go to the migration's own application only. The `credential.created`, `credential.expiring`, `credential.failed` and `credential.removed` events follow the lasting API key the cloud browser's agent made at the domain's DNS provider (made and kept, renewed by a reconnect, 30 and 7 days before its end, refused by the provider or ended, removed); each carries a `credential` object with the key's record, never the key, its `rights` (`transfer`, `billing` or `account`: what it can do beyond DNS), and `reconnect: true` when the end user should sign in again.10b:Tc9c,Starts a subscription Checkout for the caller's workspace. Requires `billing:manage` (owners and admins); a widget token is refused. The session collects the card up front, and carries the customer's `promotion_code` as its discount when one is sent (below). A new workspace's first subscription starts with a 14 day trial; a workspace inside its grace period (the retired Free plan) gets a trial that ends when its grace ends, so subscribing early never costs a day; anyone else is charged today. A workspace that already has a running subscription gets `409` (change the plan with `/billing/change-plan` instead). Nothing is granted until Stripe confirms the checkout. Supply EITHER `return_url` (embedded Checkout, the response carries `client_secret`) OR both `success_url` and `cancel_url` (hosted Checkout, the response carries `url`). `promotion_code` is optional: the text a customer typed, at most 64 characters (never a Stripe `promo_` id). It is checked here, before Stripe is asked for a session, and only CustomDomain's own codes are taken (made through the operator console, or limited to this deployment's Stripe products), because a Stripe account can be shared with other products. A code that is not CustomDomain's, does not exist or is no longer active is a `404`, the same for all three, and no session is created; a CustomDomain code that Stripe will not give this order (a first order only code, a minimum amount) is a `400`. The code becomes the session's one discount, and Stripe's own code field on its checkout page is never switched on, so a code of another product cannot be typed there either. A Checkout Session cannot be given a discount after it is created: to add, change or remove a code, start a new checkout (with the new code, or without one) and mount its `client_secret` in place of the old one. `ui_mode` is optional and picks how the session is shown. Leave it out (a `null` or an empty string counts as leaving it out), or send `embedded`, for the behavior from before it existed: Stripe Embedded Checkout when `return_url` is set, and the hosted redirect when only `success_url` and `cancel_url` are. `elements` is Elements with the Checkout Sessions API: the caller renders the whole page (the plan, the price, the trial, the promotion code box, the totals) and mounts only Stripe's Payment Element with the returned `client_secret`, so the page can wear its own theme. It needs `return_url`, which is where redirect based payment methods and the finished payment land, and the session is created on a Stripe API version of the dahlia release train (the billing guide names the exact version), so mount it with a Stripe.js of that train. The trial, the promotion codes and the card up front are the same in every mode. The response's `ui_mode` says what was really created (`embedded`, `elements` or `hosted`): an `elements` request answers `embedded` when Stripe could not create an Elements session, so read it before mounting anything. `hosted` is only ever an answer, never a request value: a client that keeps the response's `ui_mode` must not send it back (the redirect flow is chosen by sending `success_url` and `cancel_url` without `return_url`). Any other value is a 400.10c:T478,Ingest for the few mutations that happen in the customer console's own database, so the control plane never sees them. Everything the control plane changes itself is recorded by its own handler and is not accepted here. The organization, actor, address and time are derived on the server; the body names only the action, an optional target and a small before and after summary. Requires an API key whose role may manage identity settings (admin or owner); a widget JWT is refused with `403`, and a `503` means the audit log is not configured on the deployment. The console's server also records here what an operator did through its owner routes (disabling an account, signing it out, a verification resend, a password reset link, the workspace's optional pages). It presents the provisioning secret in `X-Provision-Secret`, names the workspace in `tenant_id`, and may use only the `user.*` and `workspace.features_set` verbs, which a tenant key may not. The actor is recorded as `operator`, the reason in `after.reason` is required for all of them but `user.verification_resent`, and the answer is a `500` when the log did not take the event.10d:T467,Available on every plan (it is how a Connect-only plan gets domains that serve). `cname_target` must be a public hostname that is not the platform edge; send `""` to go back to the edge. `apex_ipv4` (up to 4 public IPv4 addresses) is what root domains get on DNS providers with no ALIAS-style record; without it such roots cannot be pointed at a hostname and `POST /domains:check` reports `apex_strategy: unsupported`. Applies to new connections and to domains still waiting for DNS (pending or failed, with no records supplied or written for them). Connected domains keep the routing they connected with (their `routing` field); move one with `POST /v1/connections/{id}:retarget`. `existing_domains` in the response counts both. Refused (400) when `cname_target` resolves to the platform edge (a CNAME to it, or one of its addresses), or when `apex_ipv4` lists an edge address: such domains would verify but never be served. A `cname_target` that does not resolve yet, or a target with no `apex_ipv4`, is accepted with a `warnings` entry. Every change is recorded in the audit log (`app.routing_set`, `app.routing_cleared`).10e:T46c,Fans out the same idempotent upsert as single-domain create. Each domain is independent: a bad domain is reported `failed` and the batch continues; a domain already connected under this app returns `already`. Max 200 domains per call. Callable with an app scoped widget token or straight from your server with an API key, in which case the connections are created on the key's application, or on `application_id` when that names another application of the same tenant. A viewer's key is refused. `client_label` names the client every connection the call creates is for, the way it does on a single create: an agency adds a client's domains together under the client's name, and the Domains page shows, filters and exports it. `PATCH /connections/{id}` changes it later. `end_user_ref` is your own id for the end user, set once and never changed. A domain that already exists keeps what it has and is reported `already`. A workspace with no subscription yet connects its first ten domains, or the number an operator set, without one; the rest of a list are reported `failed` with the reason, one by one, until it starts its trial.10f:T6c5,Keeps a DNS provider or registrar key for the workspace, encrypted (GRANT_ENCRYPTION_KEY; `503` without it). The key is checked first by listing the provider's domains, or, for a provider that cannot list them, by reading one of the selected domains or `check_domain`; with neither, `400` `check_domain_required`, and a key is never kept unchecked. `access` is `continuous` (kept until revoked, used only to put back records it wrote that disappear where the deployment has automatic repair on, remove records when a domain is removed, and re-apply the records it wrote on request) or `one_time` (usable for an hour, and deleted as soon as the chosen domains are connected or the hour passes). `scope` is `all` of the account's domains or `selected` ones. The key is never returned. A provider whose credential is a login or a short lived token (ALL-INKL, Arsys, Azure DNS, Binary Lane, Google Cloud DNS, INWX, Loopia, Openprovider, Plesk, Subreg) is used once and never kept: `access` defaults to `one_time` for it, and `continuous` answers `422` `use_once_credential`. Anyone whose role operates applications may connect a key and read the accounts. Renaming an account, changing its access, scope or domains, listing the domains its key reaches, connecting domains with it, replacing its key, renewing it by signing in again, checking it and removing it take an admin, an owner or the member who connected it (`can_manage`); a key a customer's sign-in made, which no member connected, is managed by an admin or an owner alone. Every change, every Check now (`provider_account.checked`) and every call that connects domains (`provider_account.domains_connected`) is recorded in the audit log (`provider_account.*`, `GET /audit`).110:Tdee,The workspace's provider accounts with their access mode, the domains they cover, when they were last used and when they expire, whether the caller may manage each one (`can_manage`), what needs the person (`needs_you`), what the last check of its key found (`health`), how each key was made and by whom (`made_by`) and who enforces its limit (`enforced_by`); and, in `kept_access`, the sign-ins and Domain Connect authorizations kept per domain, grouped by provider. A kept sign-in is stopped per domain with `DELETE /connections/{id}/grant`. A viewer reads them without `agent_key.account` (an end user's customer number at the provider), `agent_key.session_id`, `account_ref` and `end_user_ref`. The accounts that need the person come first (`needs_you`), then the most recently used, the never used last, newest first. `end_user_keys` counts the keys your customers' own sign-ins made, and how many customers they belong to, so a console can show them as one row; it counts them before `owner`, `q` and paging apply. `?provider=` keeps one provider's accounts. `?owner=workspace` keeps the keys the workspace holds (pasted, or made at a sign-in a member started in the console); `?owner=end_user` the keys your customers' own sign-ins made. `?q=` keeps the accounts whose label, scope domain or linked domain holds the text, and, for a member, whose `account_ref`, `agent_key.account` or `end_user_ref` does; a viewer never matches those. `?limit=` (1 to 200) and `?cursor=` (the previous answer's `next_cursor`) page the list; without `limit` the answer holds every account. `?domain=` keeps the ones that may act for that domain for the caller, best first, by the saved access resolver's rules (see `GET /connections/{id}/saved-access`), for `?application_id=` or the API key's own application (`404` for an application of another workspace), adds them as `saved_access`, and answers them in full: `limit` and `cursor` with it are `400`. A delegated agent token lists with `domains:read` (the MCP's `list-provider-accounts`), and sees less than an API key: only the workspace's keys that serve the application its grant is bound to, never a key an end user's own sign in made, each as a viewer reads it (no `account_ref`, `end_user_ref`, `agent_key.account` or `agent_key.session_id`), without the key's name (no `agent_key.name`, whichever application the key is bound to) and without who in the workspace made it (no `made_by.by` and no `created_by`; `made_by.how` stays), with only that application's connections and only the `domains` that no other application of the workspace has connected (a zone in which another application holds a domain is left out, unless the grant's own application holds one in it too), `can_manage` false, and an empty `kept_access`. `application_ids` is empty for every key it reads, since it names the workspace's other applications (`application_id` says the key serves its own). A key made for another application and shared with the grant's own one reads as ` key`, with no `application_id` (the label the agent made it with names the other application's domain), and `?q=` searches what the agent reads. `?domain=` answers an empty `accounts` and `saved_access` for a zone in which another application holds a domain (and the grant's own holds none), and when the workspace's connections cannot be read; it reads a key at its provider only for a zone the grant's own connections are in. `?application_id=` may only repeat the grant's own application (`403` otherwise). A token without `domains:read` is `403`.111:T7ec,**The console only.** Starts the secure sign in that adds a provider account with no domain: the person signs in to the provider in a temporary browser, the agent makes a lasting API key on the provider's own key page, and CustomDomain™ checks the key by listing the domains it reaches. The key then waits in memory for the keep step, which makes the account only after the person confirmed which of those domains it may use (`POST /browser-sessions/{sid}:keep`, within ten minutes). Nothing is kept before that: no `provider_accounts` row exists, and a sign in that is abandoned or left to run out names the key it made so the person can delete it at the provider (`left_key`). Only the console's own call starts one: an API key that carries the console's signed visitor forward, naming the person signed in to it. The `X-CustomDomain-Client` header and the `Origin` are labels any key holder can send, so neither counts alone, and a widget token, an end user's token, a delegated agent token and the operator's key are refused with `403` `browser_account_unavailable`. The caller must also hold a role that operates applications (an owner, an admin or a member; a viewer is `403` `forbidden`), and the request must carry an `Origin` on the server's return origin allowlist, as `browser:start` requires. A workspace an operator suspended starts none, as it starts no other cloud browser (`403` `workspace_suspended`). Only a provider whose key can be made at sign in and whose domains can be listed qualifies (`account_ways` of `GET /providers` names `secure_sign_in` for it); any other is `403` `browser_provider_not_allowed` or `409` `browser_account_unavailable`. One sign in at a time runs for a member and a provider (`409` `browser_session_active`), and three start an hour. Returns the address of the popup page, whose fragment carries a single use bootstrap code that no server sees; the popup trades it at `POST /browser-sessions:redeem`. The answers of every call about the session are `Cache-Control: no-store`.112:T706,**The console only.** Starts "Sign in with ", the way to add a provider account with no domain by the company's own OAuth consent screen. It answers the address to open in a popup. When the person approves access there, the shared sign-in callback (`GET /connect/oauth/callback`) makes the account: every domain the sign-in reaches, continuous access, with the access token and the refresh token kept encrypted (a token near its end is refreshed before it is used). The popup posts `{ok, purpose: "account", provider, account_id}` to `return_origin`, or `{ok: false, code, message}` when the person declined or it failed (`access_denied`, `oauth_failed`, `oauth_scope_not_granted`, `oauth_no_refresh`, `ProviderAuthenticationError`, `account_check_failed`); a token the account did not keep is revoked at the company. Signing in again to the same account (DNSimple's account, a Vercel team) renews the account it made before instead of adding a second one. The state binds the workspace, the member who started it and the application, is single use and lives ten minutes. Nothing is written before the callback. Offered only where `account_ways` of `GET /providers` names `oauth` for the company: the deployment runs the company's OAuth app, keeps what it hands back (`OAUTH_MANAGED_PROVIDERS` and a grant encryption key), does not hold the sign-in back, and the company's sign-in needs no domain. Any other is `403` `oauth_account_unavailable`. The caller is the console's own call, as for `POST /provider-accounts:sign-in`: an API key that carries the console's signed visitor forward, held by a member who operates applications (`403` `browser_account_unavailable` otherwise; a viewer is `403` `forbidden`). A workspace an operator suspended starts none (`403` `workspace_suspended`).113:T132b,Narrowing the scope detaches the domains it no longer covers; they stay connected, without continuous access. Switching to `one_time` deletes the key now. Switching to `continuous` needs the key still held. Changing the `label`, `access`, `scope` or `domains` takes whoever manages the account: an admin, an owner or the member who connected it (`403` otherwise, with nothing stored and nothing audited); for a key an end user's own sign-in made, which no member connected, an admin or an owner alone. A `label` is one to 80 characters once trimmed (spaces, line breaks and the byte order mark at its ends are removed), counted in characters, and holds no control or invisible character: no NUL, tab or line break, zero width space, byte order mark or text direction override (`400` `invalid_request` otherwise, and nothing in the call is stored). `continuous` access for a credential that is used once and never kept answers `422` `use_once_credential`. A change is recorded in the audit log (`provider_account.updated`, with the label, access, scope, domains and applications before and after). What each kind of account allows when `scope` or `domains` widens it (`made_by.how` names the kind). Narrowing and renaming ask nothing of the provider, for every kind, with one exception: a key made at a secure sign-in that goes from `all` back to `selected` has each domain it names that the account does not already hold read first (at most 20 a call, `400` `too_many_domains_to_check` beyond). A change that is refused stores nothing. `pasted`: any scope and any domains. The person chose the key and what it is used for, so nothing is read at the provider; connecting a domain the key cannot write is what finds it. `console_sign_in`, a key made at a secure sign-in a member started in the console: it widens only to domains the key reaches at the provider. Each domain added is read with the key, by its zone, before anything is stored. A call that names a domain the key does not reach answers `422` `zone_not_reached`, naming those domains in `domains`, and stores nothing, not even the domains that were reached. A failure that says nothing about the key (a timeout, a `5xx`) answers `503` and stores nothing. At most 20 new domains are read in one call (`400` `too_many_domains_to_check`), and an account that no longer holds its key answers `409`. Setting `scope` to `all` has no domain to read, so it needs the provider to list the domains a key reaches and this key to list them now: a provider that cannot answers `422` `scope_all_needs_list` (add the domains instead), and a key the provider refuses answers `422` `ProviderAuthenticationError`. The scope `all` is no way round the read of a domain: while it is `all`, a domain named that the account does not already hold in `domains` is read too, whether the call keeps `all` or goes back to `selected`. The change is written on the account as it is after the reads, so a renewal that landed meanwhile is kept; an account that lost its key, or whose change no longer matches what was read, answers `409` and nothing is written. Those reads (one for each new domain's zone, and the list the scope `all` needs) are taken from the workspace's hourly budget of reach checks; a zone whose answer CustomDomain™ kept from a read in the last ten minutes costs none. A change whose reads do not fit in what is left of the hour answers `429` `reach_quota` with `Retry-After`, reads nothing and writes nothing. `widget_sign_in`, a key an end user's secure sign-in made in the widget: it is never widened, whoever asks. A change that adds a domain or sets `scope` to `all` answers `403`; renaming, narrowing and removing still work. `application_ids` is the whole set of other applications of the workspace that may use a key bound to one application, besides its own (`application_id`, which always serves). Sending it replaces the set: name an application to share the key with it, leave it out to take it back, send `[]` to share with none. Naming the key's own application, a repeat or a blank changes nothing. It takes an admin or an owner, never only the member who connected the key (`403` otherwise), and answers `403` for a key an end user's sign-in made, which is never shared, and `404` for an application that is not the workspace's. A key bound to no application already serves every application, so naming one answers `422` `serves_every_application`; at most 100 are taken in a call (`400` beyond). Each application shared is recorded in the audit log as `provider_account.shared`, and each taken out as `provider_account.unshared`, both naming the applications served before and after and the ones changed (`application_ids`). Taking an application out detaches the domains of it that were using the key: they stay connected, without continuous access, and each domain's timeline records `access_revoked` with the reason `unshared`.114:Tf98,Creates a connection for each domain under its application and writes its records with the account's key (keeping the CAA and TXT values already there and recording what each write replaced). A domain goes into the application named for it, else the call's `application_id`, else the application that already holds it in the workspace (its own connection's, so a domain the workspace already serves is linked where it lives). A domain none of those names answers `400`, and so does one two applications hold; so does a domain named for two different applications. A call takes at most 200 domains (a domain named twice is one; `400` beyond). Every application used must be the workspace's (`404` otherwise) and one the key serves, and every domain must be inside the key's scope: a call that is refused for any of this changes nothing, because all of it is checked before the first write. Each domain is linked to the account once its records are written; a domain whose write fails is not linked and keeps the access it had. A continuous account then keeps the linked domains in sync. A domain the application already serves is only linked (`provider_account.relinked` in the audit log), and only to a key at the provider its DNS is at whose scope already holds it; any other such domain is answered `already` with the reason and left as it is. A one time account deletes its key once the domains are connected, even when the caller has gone away by then, and past its hour answers `409`. A domain in a zone the key does not reach fails alone (`zone_not_reached` on the connection); the account is flagged `needs_reconnect` only when the provider refuses the key itself, which is checked with a request that does not depend on the zone. A key made at a secure sign in serves its own application and the applications an admin shared it with (`application_ids`); naming any other application's id answers `403` (this key is not shared with this application; an admin or an owner can share it). A domain outside the key's scope answers `400`, naming the domains, except for a key a member of the workspace made at a sign in started in the console (the console's signed call, not an API key that names the console): when a read of the domain's zone with the key works, the domain is connected with no new sign in, and the zone is added to the key's scope once a write there works (`provider_account.domain_added` in the audit log). A zone the key does not reach answers `422` `zone_not_reached`, naming the domains, and a provider that cannot say (a timeout, a `5xx`) answers `503`, never a refusal of the key: the same two answers `PATCH /provider-accounts/{id}` gives, with nothing written. A call reads at most 20 such zones, one read for each, and answers `400` `too_many_domains_to_check` before the first read beyond that; those reads are taken from the workspace's hourly budget of reach checks, and a call whose reads do not fit in what is left answers `429` `reach_quota` with `Retry-After`, with nothing read or written; `PATCH /provider-accounts/{id}` is the other way to widen a scope. A key an end user's secure sign-in made in the widget, or one a sign in started through the API made, answers `403`: it connects domains only through that end user's own widget session. A domain the application already has, kept by such a key, is left as it is (`already`, not re-linked). Takes an admin, an owner or the member who connected the account. A call that connected at least one domain (its records written with the key, or a domain already serving now linked to the account) is recorded in the audit log as one `provider_account.domains_connected` row naming those domains, by name only, beside the `provider_account.relinked` and `provider_account.domain_added` rows it may also write; a call that connected none writes no such row. A domain already serving that was linked to this account before the call is left as it is (`already`), is not named in the row, and does not make one.115:T9c6,A new key for an account, in one of two ways (`method`). Both take an admin, an owner or the member who connected the account (`403` otherwise), and the key is recorded in the audit log (`provider_account.key_replaced`). `api_key` (the default), for a key a person pasted: for an account the provider stopped accepting, or a one time account whose key was deleted. Everything is checked before anything is kept: the access mode, then the key (listing the provider's domains, or reading `check_domain`, a selected domain or a domain the account connected, for a provider that cannot list them), and for a `selected` account that the key reaches every selected domain. `params` sent with the key replace the kept ones. A key made at a secure sign-in answers `409`: it is renewed by signing in again, not by pasting a key. `continuous` access (asked, or the account's own) for a credential that is used once and never kept answers `422` `use_once_credential`; send `access` `one_time`. `secure_sign_in`, for a key made at a secure sign-in a member started in the console: starts the same account sign in as `POST /provider-accounts:sign-in`, for the account's own provider and application, and answers `201` with `session_id` and `popup_url`. The new key swaps into this same account when the person keeps it (`POST /browser-sessions/{sid}:keep` with an empty body), so the account keeps its id, its domains, its scope and the domains linked to it; only its key changes, it is active again with its daily check started afresh, and the key it replaces is named for deletion at the provider (`replaced_key`). It is the console's own call (an API key on the signed visitor forward, `403` `browser_account_unavailable` otherwise) and takes the sign in's body (`return_origin`, `consent_version`, `locale`, `viewport_hint`) and no key. A key a person pasted is renewed by pasting (`409`), and a key a customer's own secure sign-in made is renewed by that customer, never from the console (`403`). The keep refuses a key of another provider account (`422` `different_account`): where the provider names the account, the two must be the same; where it does not (IONOS), the new key must list every domain the account holds. An account that holds no domain and has no account number gives nothing to compare, so its renewal is refused (`422` `account_not_verifiable`): remove the account and add it again with a new sign in. The refused key stays pending and is named for deletion when the sign in is cancelled.116:T9cd,Reads the account's key against its provider right now: the same one cheap call as the daily check (the provider's domain list where it gives one, else a read of one domain the account covers), and its verdict is recorded the same way. Nothing is written at the provider. The answer is the account, with its `health`, and `result`: `ok` (the provider accepted the key), `refused` (the provider refused it: the account is now `needs_reconnect`, with a timeline event for each domain it covers and an inbox item, once), or `unreachable` (the provider could not be asked or answered with an error that is not a refusal; `message` says what, and the failure counts toward the backoff and toward `needs_you` `check_failed`). A pasted key the provider had refused that works again returns to `active`, recorded in the audit log as `provider_account.updated` (`status` before and after, `via` `check_now`). A key a secure sign-in made keeps its status: it is renewed by signing in again. Every check that asked the provider is recorded in the audit log as `provider_account.checked`: who asked (`actorId`), the account (`target`), the `provider` and the `result` (`ok`, `refused` or `unreachable`), never the key and never the provider's own words. It is written whatever happens to the verdict afterwards, so a check whose verdict was dropped (`409` because the account changed while the provider answered) is on record too. A call that never asked the provider (a `403`, a `429`, a `409` because the account is a one time key, holds no key or has nothing to read the key against, or a request that ended before the provider was asked, which answers `503`, gives its minute back and spends nothing from the hourly budget of reach checks) writes nothing. Takes the workspace's API key and an admin, an owner or the member who connected the account (`403` otherwise). A key an end user's own sign-in made is never used for it (`403`), and a one time key is used once and never checked (`409`). An account whose provider cannot list its domains and which covers none answers `409` `nothing_to_check`. One check a minute for an account: a second answers `429` `rate_limited` with `Retry-After: 60`. Each check is also one read of the workspace's hourly budget of reach checks: once it is spent the call answers `429` `reach_quota` with `Retry-After`, asks the provider nothing, records nothing and keeps no minute, so the same account can be checked as soon as the hour turns. The daily check is outside that budget.117:T542,Authorizes payment (manual capture) for a domain at the retail price. Returns a Stripe checkout session whose `client_secret` drives the embedded payment element. The domain is registered only after payment completes via `POST /v1/registrar/fulfill`; the card is captured strictly after the registrar settles, so a failed registration never charges the buyer. `503` when purchasing is disabled on the deployment. `ui_mode` is optional and picks how the payment is shown. Leave it out (a `null` or an empty string counts as leaving it out), or send `embedded`, for Stripe Embedded Checkout. `elements` is Elements with the Checkout Sessions API: the caller renders the page and mounts only Stripe's Payment Element with the returned `client_secret`, so the page can wear its own theme; the session is created on a Stripe API version of the dahlia release train (the billing guide names the exact version), so mount it with a Stripe.js of that train. Authorizing now and capturing after registration works the same in both. The response's `ui_mode` says what was really created (`embedded` or `elements`; a domain payment has no redirect flow, so it is never `hosted`): an `elements` request answers `embedded` when Stripe could not create an Elements session, so read it before mounting anything. Any other `ui_mode`, `hosted` included, is a 400.118:T5c6,Refused because of the workspace's billing. `billing_required`: the workspace has no active or trialing subscription (a new workspace that has not started its trial, a Free workspace past its grace period, a comp that ended, or a subscription Stripe marked unpaid or canceled). It stops a new connection, the start of a domain purchase and the first live credential (an application, an API key or a rotated client secret). Domains already connected keep working, and an owner or admin sets up billing in the console; `details` says where. A new workspace's first domain is the exception: while it has fewer pending, propagating or live connections than its free domains (ten, unless an operator set another number: `free_domains`), a connect and the start of a purchase go through (`first_domain_free`), and the next one is refused with a `title` saying a card is needed to connect more domains. Credentials still need the trial. `quota_exceeded` (connections only): a plan that is refused past its quota (Starter, and the retired Free) is at it and the deployment enforces quotas. `connections_unavailable`: what a connect-scoped widget token, the tenant's own end user, gets instead of either (and instead of `403 workspace_suspended`), with neutral wording, so the tenant's customers are never told about the tenant's billing or account. A delegated agent token gets the full wording, and `GET /billing/standing` tells it beforehand whether a new connection would be refused.119:T4fa,Where the edge sends every visit to the domain (a `301`, keeping the visit's path and query): a plain `https://` address of a public domain, `""` to clear it. It needs edge serving, which comes with Growth and up: `402` `plan_upgrade_required` on a plan without it and `503` where the deployment has it off (clearing a forward needs neither). `400` for an address that is not https (`http:`, `javascript:`, `data:`, a scheme-less address), has a username or password (`https://acme.com@evil.example`), names an IP address, a name with no dot or a reserved name (`localhost`, `.local`, `.internal`, `.test`), or contains spaces, backslashes or hidden characters. The port is read as a number and stored once: `:443` is dropped and a leading zero is not kept (`:0443` is `443`), and a target that names this domain on port 80 or 443 is the domain itself, as the edge reads it. `422` `redirect_target_not_allowed` for a domain another workspace has connected or claimed (unless your own workspace serves it), and `422` `redirect_loop` when the target is the domain itself or a visit would come back to a host it has been through, through this domain's `www` redirect or any forward of your own domains, or goes through more than 8 forwards in a row. Not for a test mode domain.11a:T41e,Present while the agent has paused in the middle of its work and waits for the customer: the provider asks for a code (a re-authentication or a step up), shows a check, (`agreement`) shows the terms its API page asks the account holder to accept before a key is made, or (`order`) is at the customer's part of the free order that turns the provider's API on (IONOS's checkout: its terms box and Buy now, which can place a temporary hold on their card), or (`account`) the provider's account lacks details only the customer may give before its API page makes a key (Gandi: the organization's postal address and phone), which they fill in on the provider's page and save. The agent never accepts terms, places an order or types account details for them. `interactive` is true and `live_view_url` is the page's own view: the customer answers in the live view, and the keys go from their browser to the vendor, never through the control plane. Once the prompt is gone from the page the agent goes on. A password the provider asks for again keeps `hand_back`.11b:T815,Set exactly when `available` is false. `provider_has_no_oauth`: the provider publishes no OAuth rail. `oauth_client_not_registered`: it does, but this deployment has not set it up: no client registered, or an MCP server sign-in not listed in `MCP_SIGNIN_PROVIDERS` (operator task). `not_discovered`: no Domain Connect discovery answer. `template_not_onboarded`: the provider speaks Domain Connect but has not onboarded our template. `redirect_unavailable`: the provider requires our return link on a one-click apply and the template cannot carry it yet. `rail_disabled`: this way is switched off in this deployment. `custom_routing`: the application routes domains to its own infrastructure (a connect target) and the one-click templates point domains at the CustomDomain™ edge. `no_adapter`: no write adapter for the API-key rail. `unregistered` / `platform_subdomain`: the domain is blocked (see `blocked_reason`). For `rails.cloud_browser` only: `provider_not_listed` (no script for this provider, or the deployment does not offer it), `not_enabled_for_workspace` (the workspace is not on the pilot list), `oauth_available` (the provider has a sign in of its own, which wins), `script_unhealthy` (its script failed in recent sessions and the rail is paused), `vendor_unavailable` (the browser vendor failed to create sessions and the rail is paused), `monthly_cap` (the monthly browser minutes are used), `sign_in_not_wired` (the sign in token cannot be signed), `site_not_supported` (the provider keeps each account on one country site, and the site of the visitor's country is one the rail does not serve yet), `caller_cannot_start` (this caller could never start the secure sign in: an agent, a plain API call without the console, or a role that cannot write connections) and `token_not_bound` (the caller's widget token is not bound to this domain: it is bound to no domain, or only to others. Mint one with `domain` and `end_user_ref`; the widget's `getToken` is where its host hands it one. `browser:start` refuses the same token with `403 token_not_bound`).11c:T4a2,The one request to press next, read from the move alone (the same for every caller), so a card can show the button `next_step` only describes. `null` when nothing is waiting for a press: the move is copying, waiting for the registry, waiting for a person at the registrar, DNSSEC or the copy review (`copy_reviewed`), or over. Because it is the same for every caller, it can name a request the caller who reads it is refused. Four cases: `sign_in` points at `POST /v1/connections/{id}/browser:start`, which runs only from a customer's browser or the console and refuses every agent token and every API key without the console's client label (`403 browser_customer_present_only`); `retry` is refused `403 ns_not_offered` to an agent token while the application's DNS hosting is off; `retry` is refused `403 forbidden` to a widget token when the setting is off; and `retry` of a move made with a connected account is refused `403 forbidden` to an API key whose member may not use that account (another member's). A caller in one of those cases tells the person (`next_step` says what to do) and does not send the request. `rollback` is open to all three callers whatever the setting says.e3:["$","$Le5",null,{"preloaded":{"docs":{"./openapi-v1.yaml":{"openapi":"3.2.0","info":{"title":"CustomDomain™ Control-Plane API","version":"1.0","description":"$e6","license":{"name":"Apache-2.0","identifier":"Apache-2.0"}},"servers":[{"url":"https://api.customdomain.ai/v1","description":"Hosted control-plane"},{"url":"http://localhost:8080/v1","description":"Local control-plane"}],"security":[{"apiKey":[]}],"tags":[{"name":"Tenancy","description":"Operator provisioning: tenants and one-call signup."},{"name":"Applications","description":"Applications and their long-lived API keys."},{"name":"Members","description":"Multi-user tenancy: invites, roles, and membership."},{"name":"Tokens","description":"Minting short-lived widget JWTs for the browser."},{"name":"Domains","description":"Read-only domain / DNS-provider feature detection."},{"name":"Connections","description":"The connect pipeline for one customer domain, across all four rails."},{"name":"Managed DNS","description":"CustomDomain™ hosts a domain's whole zone after the user points its nameservers at us once, and writes every record from then on."},{"name":"Nameservers","description":"Move an end user's nameservers to the platform's DNS host, with their consent, and back. Per application, with analytics."},{"name":"Secure","description":"Edge-managed TLS certificates (SSL) for connected domains: issue, renew, import, deprovision."},{"name":"Power","description":"The edge reverse-proxy for a connection: origin, apex↔www redirect, and root-path serving."},{"name":"Sharing","description":"Forward-to-a-colleague share links that resume a connect flow from a server-side prefill."},{"name":"Providers","description":"The DNS-provider capability catalog and parity census."},{"name":"Templates","description":"One-click setup service templates and apply-URL building."},{"name":"Registrar","description":"Domain search, quote, and purchase (Sell)."},{"name":"Monitor","description":"Checking declared records against live public DNS (drift)."},{"name":"Webhooks","description":"Registering receivers and inspecting delivery attempts."},{"name":"Billing","description":"Plans, metered usage, the subscription (trial, grace, invoices), checkout, and the billing portal."},{"name":"Enterprise","description":"RBAC reference matrix and the audit log."},{"name":"Meta","description":"Public service discovery and capability advertisement."},{"name":"Analytics","description":"The tenant's connect funnel, connection outcomes, and the traffic its domains receive at the edge."},{"name":"Provider accounts","description":"DNS provider and registrar keys a workspace connects once, with one time or continuous access, for some or all of the account's domains."},{"name":"Cloud browser","description":"Sign in to a DNS provider that offers no sign in of its own, inside a temporary browser, with the customer present. The customer types their own password into the provider's real page; CustomDomain™ never receives it. Our software then reads the provider's DNS page for one domain, shows the exact changes, and makes them only after the customer approves. Off unless the deployment turns it on."},{"name":"Agents","description":"AI assistants acting for a workspace. An agent registers, a person approves what it may do in the console, and it works with a short lived token until the grant is revoked. The hosted MCP server accepts these tokens. The authorization server metadata (RFC 8414) and the signing keys (RFC 7517) are served on the API origin at `/.well-known/oauth-authorization-server` and `/.well-known/jwks.json`."}],"paths":{"/tenants":{"post":{"operationId":"createTenant","summary":"Create a tenant","tags":["Tenancy"],"description":"Operator provisioning endpoint. Requires the management key in production.","security":[{"managementKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}}}}},"responses":{"201":{"description":"Tenant created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tenant"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}}}},"/tenants/{id}":{"get":{"operationId":"getTenant","summary":"Get a tenant","tags":["Tenancy"],"security":[{"managementKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Tenant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tenant"}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"updateTenant","summary":"Rename your workspace","tags":["Tenancy"],"description":"The caller's own tenant only (admin and above); any other id is a `404`.","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":80}}}}}},"responses":{"200":{"description":"Renamed","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/tenants:provision":{"post":{"operationId":"provisionTenant","summary":"One-call signup provisioning (tenant + owner + app + API key)","tags":["Tenancy"],"description":"Atomically creates a tenant, its first owner member, a default application, and a long-lived API key. `api_key` and `client_secret` are returned ONCE. Guarded by the dedicated provision secret (the `X-Provision-Secret` header or a Bearer token) so the customer console's server can hold this narrow secret instead of the operator management key. It also mints the workspace default key (see `POST /tenants/{tenant_id}/default-key`) and returns it ONCE as `default_api_key` with its id; both fields are absent if it could not be made, and the default key route makes it later.","security":[{"provisionSecret":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tenant_name"],"properties":{"tenant_name":{"type":"string"},"app_name":{"type":"string"},"owner_email":{"type":"string"},"environment":{"$ref":"#/components/schemas/Environment"}}}}}},"responses":{"201":{"description":"Provisioned (api_key + client_secret shown once)","content":{"application/json":{"schema":{"type":"object","required":["tenant_id","application_id","api_key","client_secret"],"properties":{"tenant_id":{"type":"string"},"application_id":{"type":"string"},"api_key":{"type":"string","description":"cd_live_… or cd_test_…; shown once"},"client_secret":{"type":"string","description":"mints widget JWTs; shown once"},"default_api_key":{"type":"string","description":"The workspace default key, cd_live_… or cd_test_…; shown once. Absent when it could not be made."},"default_api_key_id":{"type":"string","description":"The default key's id; present with default_api_key."}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/tenants/{tenant_id}/default-key":{"post":{"operationId":"ensureDefaultApiKey","summary":"Ensure the workspace default key exists (secret returned only when created)","tags":["Tenancy"],"description":"The workspace default key is an ordinary API key (`cd_live_…` in production) flagged `is_default`, at most one active per workspace, whose secret the customer console keeps sealed so the workspace's owner can view it more than once. It acts with admin authority, never owner: it cannot make, unmake or remove an owner, delete the workspace, or create API keys (`403`). Server to server, guarded by the provision secret like `tenants:provision`; a missing and a wrong secret get the same `401`. With no active default key this creates one and answers `201` with the full secret ONCE in `api_key`. With one, it answers `200` with its id and prefix and no secret (a caller that lost its copy rotates instead). Not subject to the billing activation gate: the key adds no capability the workspace's console key does not already hold.","security":[{"provisionSecret":[]}],"parameters":[{"name":"tenant_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"An active default key exists; no secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiKey"}}}},"201":{"description":"Created; api_key is the full secret, shown once","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiKey"}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/tenants/{tenant_id}/default-key:rotate":{"post":{"operationId":"rotateDefaultApiKey","summary":"Rotate the workspace default key (new secret returned once)","tags":["Tenancy"],"description":"Mints a new default key and revokes the old active one in one transaction: the old key stops authenticating at once, and there is never a moment with two active default keys or none. The workspace's other keys are untouched. With no active default key it simply creates one. Same provision secret guard as `POST /tenants/{tenant_id}/default-key`.","security":[{"provisionSecret":[]}],"parameters":[{"name":"tenant_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Rotated; api_key is the new full secret, shown once","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiKey"}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/stats":{"get":{"operationId":"getStats","summary":"Aggregate counts across all tenants (operator)","tags":["Tenancy"],"description":"How many tenants, accepted members and pending invites the control plane holds. An operator surface for the owner dashboard, gated by the management key: no tenant API key can reach it, and it carries no tenant data. `members` counts accepted members only (owners and teammates who signed up); an invite that was sent and never accepted counts under `pending_invites`, so the two add up to the members table.","security":[{"managementKey":[]}],"responses":{"200":{"description":"Counts","content":{"application/json":{"schema":{"type":"object","required":["tenants","members","pending_invites"],"properties":{"tenants":{"type":"integer"},"members":{"type":"integer","description":"Accepted members only."},"pending_invites":{"type":"integer","description":"Invites sent and not yet accepted."}}}}}},"401":{"$ref":"#/components/responses/Error"}}}},"/applications":{"post":{"operationId":"createApplication","summary":"Create an application (client_secret returned once)","tags":["Applications"],"description":"$e7","security":[{"managementKey":[]},{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"tenant_id":{"type":"string","description":"Required with the management key, where it selects the tenant. Ignored with a tenant API key, which always creates the application in its own tenant."},"name":{"type":"string"},"environment":{"$ref":"#/components/schemas/Environment"},"sandbox":{"type":"boolean","description":"Create a test mode application (see above). Fixed for the life of the application."}}}}}},"responses":{"201":{"description":"Created (client_secret present only here)","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Application"},{"type":"object","properties":{"client_secret":{"type":"string","description":"mints widget JWTs; shown once"}}}]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/BillingRequired"}}},"get":{"operationId":"listApplications","summary":"List applications","tags":["Applications"],"description":"With an API key: the caller's own tenant's apps. A **test mode** key lists only its own application, which is how a server learns which application a key belongs to. With the management key: `?tenant_id=` selects the tenant.","security":[{"apiKey":[]},{"managementKey":[]}],"parameters":[{"name":"tenant_id","in":"query","required":false,"schema":{"type":"string"},"description":"Required only when listing with the management key."}],"responses":{"200":{"description":"Applications","content":{"application/json":{"schema":{"type":"object","required":["applications","count"],"properties":{"applications":{"type":"array","items":{"$ref":"#/components/schemas/Application"}},"count":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}}}},"/applications/{id}":{"get":{"operationId":"getApplication","summary":"Get an application","tags":["Applications"],"description":"Returns the application with its settings. `end_user_saved_access` says whether a returning end user may reuse the access their own secure sign-in kept (change it with `PATCH /applications/{id}`), and `secure_sign_in` says whether the secure sign-in can run for the workspace at all (read only). Every answer that carries an application has both: the list, the create and the update too.","security":[{"managementKey":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Application","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Application"}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"updateApplication","summary":"Rename an application or change its settings","tags":["Applications"],"description":"$e8","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"additionalProperties":false,"properties":{"name":{"type":"string","maxLength":80},"nameserver_migration":{"type":"object","required":["mode"],"properties":{"mode":{"type":"string","enum":["off","offer","prefer"]},"target":{"$ref":"#/components/schemas/NameserverTarget"}}},"end_user_saved_access":{"type":"boolean","description":"Whether a returning end user may reuse the access their own secure sign-in kept, for their next domain in this application, after one tap of consent."}}}}}},"responses":{"200":{"description":"Application","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Application"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"deleteApplication","summary":"Delete an application","tags":["Applications"],"description":"Deletes one of your applications together with what belongs only to it: its API keys stop working, and its webhook endpoints, share links and settings are removed. Needs an admin or owner key (it revokes keys). Another tenant's application is a 404.\n\nRefused with `409` when deleting would break something that works, each with the reason in `details`: `default_application` (your workspace's default application, the oldest one: the signup key and your team's access belong to it, so it also keeps your last application), `application_key_in_use` (the key making the request belongs to this application) and `application_has_domains` (it still has domains, in any state; disconnect them first with `DELETE /connections/{id}`).","security":[{"apiKey":[]},{"managementKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"204":{"description":"Deleted"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/applications/{id}/keys":{"post":{"operationId":"createApiKey","summary":"Issue an API key for an application (key returned once)","tags":["Applications"],"description":"Needs `keys:manage` (admin and above). A key minted with a member's key acts with that member's role. The workspace default key (`is_default`) cannot create keys (`403`): a key it minted would not carry its admin limit.","security":[{"apiKey":[]},{"managementKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"environment":{"$ref":"#/components/schemas/Environment"}}}}}},"responses":{"201":{"description":"Created; the full secret is present only in this response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiKey"},{"type":"object","properties":{"key":{"type":"string","description":"cd_live_… or cd_test_…; shown once, stored hashed"}}}]}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/BillingRequired"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"listApiKeys","summary":"List an application's API keys (secrets omitted)","tags":["Applications"],"security":[{"apiKey":[]},{"managementKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Keys (metadata only; the secret is never returned again)","content":{"application/json":{"schema":{"type":"object","required":["keys"],"properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/applications/{id}/keys/{keyId}":{"delete":{"operationId":"revokeApiKey","summary":"Revoke an API key","tags":["Applications"],"security":[{"apiKey":[]},{"managementKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"},{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Revoked"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/members":{"post":{"operationId":"inviteMember","summary":"Invite a member to the caller's tenant","tags":["Members"],"description":"Creates a pending member and its single-use invite link. The response carries `invite_token`; send the invitee a link built from it. The link works for 7 days, after which the member is reported as `expired` until an admin resends or revokes it. The inviter's email is taken from the credential that sends the invite, never from the body. Requires admin or owner (`member:manage`); a caller cannot invite a role above their own, and `owner` is reached only by promoting an existing member.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"role":{"$ref":"#/components/schemas/Role"},"inviter_name":{"type":"string","description":"Display name of the person sending the invite, shown to the invitee. Optional; at most 80 characters."}}}}}},"responses":{"201":{"description":"Invited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Member"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"listMembers","summary":"List the caller tenant's members","tags":["Members"],"description":"Every member and pending invite of the caller's tenant, each with its `status`: `active` once accepted, `pending` while its invite link works, `expired` once the link has lapsed. Invite tokens never appear here.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Members","content":{"application/json":{"schema":{"type":"object","required":["members"],"properties":{"members":{"type":"array","items":{"$ref":"#/components/schemas/Member"}}}}}}},"401":{"$ref":"#/components/responses/Error"}}}},"/members:preview":{"post":{"operationId":"previewInvite","summary":"Preview an invite by its token, without accepting it","tags":["Members"],"description":"What an invite link is for: the invited email, the workspace, the role, who sent it, and whether it still works. Nothing is accepted or spent. Public: the token is the capability, exactly as for `members:accept`, and it travels in the body so it never lands in an access log. A link that stopped working says why (`accepted`, `expired`, `revoked`, or `replaced` by a newer invite to the same address); a token that was never issued is a 404. Rate-limited per client address.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"The invite token from the invite link."}}}}}},"responses":{"200":{"description":"The invite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitePreview"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/members:accept":{"post":{"operationId":"acceptMember","summary":"Accept an invite (single-use token)","tags":["Members"],"description":"Accepts the invite and returns the member with a member-scoped API key for the inviter's tenant. The token is the capability, so no API key is needed; when `email` is supplied it must match the invited email. The token is spent on success, once. A second accept that races the first, or one racing a resend that replaced the link, is refused with 409. A repeat after the accept has finished finds no invite and answers 404, as does a link for an invite that was removed. A pending invite whose link has lapsed is refused with 410 `invite_expired`.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string"},"email":{"type":"string","description":"When supplied, must match the invited email."},"user_id":{"type":"string","description":"The accepting user's id in the calling application, recorded as `invited_by`."}}}}}},"responses":{"200":{"description":"Accepted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Member"},{"type":"object","required":["application_id","api_key"],"properties":{"application_id":{"type":"string","description":"The inviter tenant's default application."},"api_key":{"type":"string","description":"Member-scoped API key for the inviter's tenant; shown once."}}}]}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"}}}},"/members/{id}":{"patch":{"operationId":"updateMemberRole","summary":"Change a member's role (owner-protected)","tags":["Members"],"description":"Demoting the tenant's last owner is refused with 400, also when two demotions or removals of owners race each other. A 409 means the member's role changed after this request read it; reload and retry.","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["role"],"properties":{"role":{"$ref":"#/components/schemas/Role"}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Member"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"removeMember","summary":"Remove a member or revoke a pending invite (owner-protected)","tags":["Members"],"description":"Removing a member revokes their member-scoped API keys at once, on every application of the workspace (the console key and any key they minted). Revoking a pending invite stops its link working; a preview of that link then reports `revoked`. The last owner cannot be removed (400), and a 409 means the member's role changed after this request read it.","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"204":{"description":"Removed"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/members/{id}/invite":{"get":{"operationId":"getMemberInvite","summary":"Get a pending member's current invite token","tags":["Members"],"description":"Returns the pending member with its current `invite_token`, so an admin can copy the link again. Reading it changes nothing: the link already sent keeps working. Requires admin or owner (`member:manage`). A member who already joined has no invite: 404.","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"The pending member and its invite token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Member"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/members/{id}/invite:resend":{"post":{"operationId":"resendMemberInvite","summary":"Re-issue a pending invite with a fresh link","tags":["Members"],"description":"Gives a pending (or expired) invite a new token that works for another 7 days and returns it as `invite_token`; send the invitee a link built from it. The previous link stops working at once, and a preview of it reports `replaced`. Requires admin or owner (`member:manage`). A member who already joined, or an invite accepted or replaced while this request ran, is a 409.","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"inviter_name":{"type":"string","description":"Display name of the person resending, shown to the invitee. Optional; at most 80 characters."}}}}}},"responses":{"200":{"description":"Re-issued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Member"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/notifications:test":{"post":{"operationId":"sendTestNotification","summary":"Send a test push to the signed in person's devices (console server)","tags":["Members"],"description":"Pushes one test notification to every browser in which `user_id` turned push notifications on. The console's server calls this behind its \"Send a test notification\" button, guarded by the provision secret exactly like `POST /members:email-changed`: the console has already checked the session and passes the signed in person's id, and the route takes no account, so a secret for one workspace cannot name another. The control plane holds the VAPID keys; without them it answers 503 `push_not_configured`. More than five tests a minute for one person answer 429 `rate_limited` with `Retry-After: 60`.","security":[{"provisionSecret":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_id"],"properties":{"user_id":{"type":"string","maxLength":128,"description":"The signed in person's id in the console."}}}}}},"responses":{"200":{"description":"What the test did","content":{"application/json":{"schema":{"type":"object","required":["devices","sent","removed","failed"],"properties":{"devices":{"type":"integer","description":"Browsers the person has turned push on in."},"sent":{"type":"integer","description":"Push services that accepted the message."},"removed":{"type":"integer","description":"Devices found gone and removed."},"failed":{"type":"integer","description":"Pushes that did not go through."}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/members:email-changed":{"post":{"operationId":"memberEmailChanged","summary":"A member's email change was confirmed (console server)","tags":["Members"],"description":"The console's server calls this once a person's email change is confirmed, guarded by the provision secret like `POST /tenants:provision`. By then the console has already corrected the member row it shares with the control plane, so `email` is the member's new, saved address. The control plane's one job here is to mirror the change to the CRM contact for that member (owner or teammate), best effort and never blocking the console: it answers `ok: true` as soon as the mirror is queued.","security":[{"provisionSecret":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tenant_id","email"],"properties":{"tenant_id":{"type":"string"},"email":{"type":"string","description":"The member's new address. Lower cased by the control plane."}}}}}},"responses":{"200":{"description":"Mirror queued","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}}}},"/tokens":{"post":{"operationId":"createWidgetToken","summary":"Exchange application credentials for a short-lived widget JWT","tags":["Tokens"],"description":"Server-side only. Trade an application's `client_secret` for a short-lived widget JWT the browser can use on the Connect endpoints. Never ship the `client_secret` or an API key to the browser.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["application_id","client_secret"],"properties":{"application_id":{"type":"string"},"client_secret":{"type":"string"},"domain":{"type":"string","description":"Optional. Binds the token to a single hostname."},"domains":{"type":"array","items":{"type":"string"},"description":"Optional. A list of hostnames the token may act on, so a multi-domain flow needs one token instead of one per domain. Each entry is normalized and duplicates and blanks are dropped. Additive to `domain`; omit both for a token that is not bound to a hostname."},"end_user_ref":{"type":"string","maxLength":256,"description":"Optional. Binds the token to one end user: your own id for them. A connection created with the token is stamped with it (a different `end_user_ref` in the create body is refused), and an end user's token removes a domain, or reads its monitoring, services and timeline, only when it is bound to the domain and minted with the connection's own `end_user_ref`."},"end_user_email":{"type":"string","format":"email","maxLength":254,"description":"Optional. The email address of the end user this token is for. It is never put in the token: it is kept on our side and a connection created with this token takes it, so that after a Move the person gets the new DNS records by email on your behalf. An `end_user_email` on the connection create wins over it."},"scope":{"type":"string","enum":["connect","app"],"default":"connect","description":"`connect` (the default) is an END USER's token for the widget: it runs the connect flow for a domain (check, create, read its own connection, verify, one-click and OAuth starts, sharing, telemetry, diagnose) and nothing else, because it lives in that end user's browser. `app` lets your server act as the whole application (list every connection, manage webhooks, configure SSL and Power, bulk create, purchases). Never hand an `app` token to a browser."}}}}}},"responses":{"201":{"description":"Token issued","content":{"application/json":{"schema":{"type":"object","required":["token","token_type","expires_in"],"properties":{"token":{"type":"string","description":"the widget JWT (Bearer)"},"token_type":{"type":"string","examples":["Bearer"]},"expires_in":{"type":"integer","description":"lifetime in seconds (default 900)"},"scope":{"type":"string","enum":["connect","app"],"description":"the scope the token was minted with"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"429":{"description":"`rate_limited`: too many token requests from this address, or too many failed ones (unknown application or wrong secret) for this `application_id`. A request with the right secret is limited only by its address. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/domain-connect-check":{"get":{"operationId":"publicDomainConnectCheck","summary":"Check one-click setup support for a domain (public)","tags":["Domains"],"description":"Unauthenticated helper behind the free Domain Connect support checker tool. Answers whether a domain's DNS provider supports one-click setup: it runs the same detection cascade as the widget (Domain Connect discovery probed ahead of NS-pattern matching) and cross-references the provider census. Results are cached for 24 hours per domain and the endpoint is rate-limited per IP; do not build product flows on it. Use the authenticated `domains:check`, which carries records-aware conflict and apex verdicts.","security":[],"parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string"},"description":"Hostname to check, e.g. example.com"}],"responses":{"200":{"description":"Detection result","content":{"application/json":{"schema":{"type":"object","required":["domain","setup_type","one_click","domain_connect"],"properties":{"domain":{"type":"string","description":"canonicalized hostname"},"setup_type":{"type":"string","enum":["automatic","manual"]},"provider_id":{"type":"string","description":"census id of the detected provider"},"provider_name":{"type":"string"},"rail":{"type":"string","enum":["oauth","api","dc","manual"],"description":"census routing for the detected provider"},"one_click":{"type":"boolean","description":"true when the user only approves: an OAuth-routed provider, or a Domain Connect provider whose template check shows it holds our template"},"domain_connect":{"type":"object","required":["supported","sync","async"],"properties":{"supported":{"type":"boolean","description":"the provider can complete a one-click Domain Connect setup of our template here"},"sync":{"type":"boolean"},"async":{"type":"boolean"},"provider":{"type":"string","description":"provider name from DC discovery"}}},"also_provider":{"type":"object","description":"The second way, as `domains:check` names it: for a former Google Domains name `provider_id` is `squarespace` (the registrar, found over RDAP) and this is `gcpdns`, whose nameservers it keeps. Absent otherwise.","required":["provider","provider_name","reason"],"properties":{"provider":{"type":"string"},"provider_name":{"type":"string"},"reason":{"type":"string","enum":["former_google_domains"]}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/domains:check":{"post":{"operationId":"checkDomain","summary":"Detect where a domain's DNS lives and how it will be set up","tags":["Domains"],"description":"$e9","security":[{"widgetJWT":[]},{"apiKey":[]},{"agentToken":["domains:read"]},{"agentToken":["domains:connect"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string"},"application_id":{"type":"string","description":"With an API key, the application to check for (defaults to the key's own). A widget JWT may only omit it or send its own application id (403 otherwise)."}}}}}},"responses":{"200":{"description":"Detection result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainCheck"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/connections":{"post":{"operationId":"createConnection","summary":"Create a domain connection (idempotent per app + domain)","tags":["Connections"],"description":"$ea","security":[{"widgetJWT":[]},{"apiKey":[]},{"agentToken":["domains:connect"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"description":"The body is decoded with unknown fields REJECTED, so the properties below are exactly the accepted set: any other key is a `400`. Everything besides `domain` is optional.","properties":{"domain":{"type":"string"},"application_url":{"type":"string","format":"uri","description":"Origin the edge reverse-proxies this connection's traffic to (Power). Validated on the way in: it must be an absolute `http(s)` URL with a public host; private, loopback and cloud-metadata targets are rejected with a `400`. Power is part of the Growth plan and up: on a plan without it the create is refused with `402 plan_upgrade_required` and nothing is stored. Omit to leave the edge on its own router."},"www_redirect":{"type":"boolean","default":false,"description":"Serve an apex↔www redirect for this connection."},"override_spf":{"type":"boolean","default":false,"description":"Replace an existing SPF record instead of merging into it. Honoured only for providers whose connection check reports `spf_override_support` as true; for every other provider the existing record is merged, as when this is false."},"validate_dmarc":{"type":"boolean","default":false,"description":"Accepted, stored with the connection and echoed back. It is not acted on yet: DMARC is not checked during verification today."},"validate_caa":{"type":"boolean","default":false,"description":"Adds the two apex CAA records that authorize Let's Encrypt (`issue` and `issuewild`) to the connection's desired record set, skipping any already present. No separate CAA check is run against the domain's existing records. Edge routing only: a domain routed to your own infrastructure (a connect target) gets its certificate there, so no CAA records are added for it."},"monitor":{"type":"boolean","default":true,"description":"Enrol the domain in drift monitoring: once the connection goes live the control plane registers a drift watch and the hourly sweeper re-checks the connection's DNS records, emitting `domain.record_missing` / `domain.record_restored` when they change. Unlike the four flags above this one DEFAULTS TO TRUE: omitting it enrols the domain. That is deliberate back-compat: the watch used to be registered unconditionally, so every connection created before this flag was honoured is monitored, and every existing integrator omits the field. Send `false` to opt a connection out; the value is echoed on the connection and is the only thing that decides whether the watch is registered. The plan's Monitor entitlement is not enforced today: monitoring is registered for every connection that has this on, regardless of plan."},"batch_id":{"type":"string","description":"Caller-supplied id correlating every domain connected in one multi-domain session. Stamped on each connection and echoed back; empty for a standalone connect. Set once at create."},"end_user_ref":{"type":"string","description":"The integrator's OWN identifier for the end user this connect is attributed to, so the console can render \"Connected by …\" and search by customer. Empty ⇒ a console/direct connect. Set once at create and never mutated. It binds a widget token and saved access to the connection, so it is an id and not a name: to name the client a domain is for, send `client_label`."},"client_label":{"type":"string","maxLength":200,"description":"The name of the client or customer this domain is for, shown in the console beside the domain and used by its client filter. Trimmed to one line, at most 200 characters, with characters that draw nothing dropped; a name with nothing left stores no name. Unlike `end_user_ref` nothing is bound to it, and `PATCH /connections/{id}` changes it later. Only an API key or an `app`-scoped token may send it: an end user's widget token or a delegated agent token that does is refused with `403`. A replay of a domain that already exists keeps the name it has."},"end_user_email":{"type":"string","format":"email","maxLength":254,"description":"Optional. The email address of the end user this domain is connected for. After a Move they get one email with the new DNS records, sent on your behalf and naming your application (at most 3 per connection in 30 days). It wins over an address given when the token was minted, is stored only on the connection, and is shown back only in this call's response and on `GET /connections/{id}` with an API key. Only an API key replaces an address the connection already has: a widget token's create keeps the stored one (as `PUT /connections/{id}/end-user-email` answers it with `409`), and a delegated agent token that sends one is refused with `403`, since the reconnect email goes to this address and carries a link that signs in as the end user. For the same reason a widget token bound to another end user than the connection's (`end_user_ref`) stores no address, neither this one nor one given when the token was minted, and is not asked for one."},"application_id":{"type":"string","description":"API key callers only: create the connection on this application of the key's tenant. A widget or agent token may only name its own application (anything else is a `403`)."}}}}}},"responses":{"200":{"description":"Existing connection replayed (idempotent)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionWithRecords"}}}},"201":{"description":"Connection created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionWithRecords"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/BillingRequired"},"403":{"description":"`forbidden` (the credential may not do this, or `application_id` or `end_user_ref` does not match the token's), `token_wrong_end_user` (a widget token: the application already has a connection for this domain that names another end user, or names one while the token names none; nothing of it is shown or changed, so mint the token with this domain's `end_user_ref`), or `workspace_suspended` (see the `ForbiddenOrSuspended` response).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`domain_already_connected`: another application already serves this domain live. Disconnect it there first, then connect it here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`apex_not_supported`: the domain is a root domain, the application routes to its own infrastructure, the domain's DNS provider has no ALIAS-style record, and the application has no `apex_ipv4` to use instead. Connect a subdomain such as `www`, or add root addresses to the application's routing (`PUT /applications/{id}/connect-target`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listConnections","summary":"List connections","tags":["Connections"],"description":"$eb","security":[{"apiKey":[]},{"widgetJWT":[]},{"agentToken":["domains:read"]}],"parameters":[{"name":"app_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ConnectionStatus"}},{"name":"dns_hosting","in":"query","required":false,"description":"Keep only the connections by who runs their DNS. `hosted`: the nameservers point at a zone we run, so the domain's DNS is served from it. `moving`: the zone is being set up or the nameservers are being moved. `any`: every domain with DNS hosting in play (hosted, moving or failed). Omit for all connections.","schema":{"$ref":"#/components/schemas/ConnectionDnsHostingFilter"}},{"name":"limit","in":"query","required":false,"description":"Rows per page. Defaults to 500; values above 1000 are clamped to 1000.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":500}},{"name":"cursor","in":"query","required":false,"description":"Opaque keyset cursor taken verbatim from a previous response's `next_cursor`. Omit for the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Connections","content":{"application/json":{"schema":{"type":"object","required":["connections","count"],"properties":{"connections":{"type":"array","items":{"$ref":"#/components/schemas/Connection"}},"count":{"type":"integer","description":"Rows in THIS page, not the tenant total."},"next_cursor":{"type":"string","description":"Present only when further rows remain. Pass it back as `?cursor=` to fetch the next page."}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}}},"/connections:count":{"get":{"operationId":"countConnections","summary":"Count the tenant's connections (no rows)","tags":["Connections"],"description":"The tenant's connection histogram, computed server-side in one grouped query. Use this instead of paging `GET /connections` when you only need totals (dashboards, quota meters, per-application domain counts). The numbers are exact regardless of how many connections the tenant has.\n\n`by_status` carries only statuses that actually occur: an absent key means **zero**, never \"unknown\". Optional `?app_id=` / `?status=` narrow the aggregate exactly as they narrow the list; a `status` outside the enum is rejected with **400**.\n\nAPI key only: this is a tenant-wide aggregate, so a per-application widget JWT cannot read it.","security":[{"apiKey":[]}],"parameters":[{"name":"app_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ConnectionStatus"}}],"responses":{"200":{"description":"Connection counts","content":{"application/json":{"schema":{"type":"object","required":["total","by_status","by_application"],"properties":{"total":{"type":"integer"},"by_status":{"type":"object","additionalProperties":{"type":"integer"}},"by_application":{"type":"array","items":{"type":"object","required":["application_id","total","by_status"],"properties":{"application_id":{"type":"string"},"total":{"type":"integer"},"by_status":{"type":"object","additionalProperties":{"type":"integer"}}}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}":{"get":{"operationId":"getConnection","summary":"Get a connection with its authoritative record set","tags":["Connections"],"description":"$ec","security":[{"widgetJWT":[]},{"apiKey":[]},{"agentToken":["domains:read"]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionWithRecords"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/ForbiddenOrWrongEndUser"},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"updateConnection","summary":"Change a domain's client name, www redirect or forwarding","tags":["Connections"],"description":"$ed","security":[{"apiKey":[]},{"widgetJWT":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionUpdate"}}}},"responses":{"200":{"description":"The connection as it is now, with its records","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionUpdated"}}}},"400":{"description":"`invalid_request`: an unknown field, a field of the wrong type, no field at all, a `client_label` over 200 characters or with nothing in it a person can read (only `\"\"` clears a name), or a `redirect_to` that is not a plain https address of a public domain (the reason is in `details`). `payload_too_large`: see the error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"description":"`forbidden`: a viewer's key, an end user's widget token or an agent token. `sandbox_not_allowed`: `www_redirect` or `redirect_to` on a test mode domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"`conflict`: the domain is being removed (also when the removal starts while the change waits its turn).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`www_redirect_apex_only`: `www_redirect: true` on a subdomain. `redirect_target_not_allowed`: `redirect_to` names a domain another workspace has connected or claimed, whether or not it is serving yet (a domain your own workspace serves is yours to forward to, whoever else has a pending or failed claim on it). `redirect_loop`: a visit would go round in a circle (taking a forward off a domain whose `www` redirect is on counts: the visit then goes to the `www` name), or through more than 8 forwards in a row (the `title` says \"too many forwards\" for that); `details` lists the hosts, naming only the ones you may see (your workspace's, and for an `app`-scoped token its own application's) and `another domain` for the rest.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal_error`: a store failed, or a check could not be made, so the change was refused (a forward is never stored when the owner of its domain cannot be read). When only `client_label` could not be written, the redirect change sent with it is stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/RedirectsBusy"}}},"delete":{"operationId":"disconnectConnection","summary":"Remove a domain, removing or keeping the DNS records we added","tags":["Connections"],"description":"$ee","security":[{"widgetJWT":[]},{"apiKey":[]},{"agentToken":["domains:disconnect"]}],"parameters":[{"$ref":"#/components/parameters/Id"},{"name":"records","in":"query","required":false,"schema":{"type":"string","enum":["remove","keep"]},"description":"What to do with the DNS records we added."},{"name":"confirm","in":"query","required":false,"description":"The domain being removed, as written on the connection (case, scheme, path and a trailing dot do not matter). Required of a delegated agent token: without it the answer is `400 confirmation_required`. Any credential that sends it, an API key or an application token included, gets `409 confirmation_mismatch` when it names another domain (`400 confirmation_required` when it is empty). Nothing is removed either way. A credential other than an agent token may leave it out.","schema":{"type":"string","examples":["shop.acme.com"]}}],"responses":{"200":{"description":"Removed; what happened to the records","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisconnectResult"}}}},"204":{"description":"Removed (no records choice given): records taken out only through a kept Domain Connect authorization, a kept sign-in or our hosted zone, kept otherwise"},"400":{"description":"`confirmation_required`: a delegated agent token did not send `confirm`, or a caller sent it empty; `details` names the domain to send. `invalid_request`: `records` is neither `remove` nor `keep`. Nothing was removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"`reauthorization_required`: removing the records needs one more sign-in or key; `plan` is the removal plan. `removal_in_progress`: another removal of the domain is running. `confirmation_mismatch`: `confirm` names another domain. Nothing was changed.","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["reauthorization_required","removal_in_progress","confirmation_mismatch"]},"title":{"type":"string"},"details":{"type":"string"},"plan":{"$ref":"#/components/schemas/RemovalPlan"}}}}}}}}},"/connections/{id}/removal":{"get":{"operationId":"getRemovalPlan","summary":"What removing a domain would do with its DNS records","tags":["Connections"],"description":"Read-only. Lists the records we added, what each one did to its name when we wrote it (created, added to a shared set, replaced, merged) and what it held before when we know, what a removal would do with each, whether that can happen automatically, needs one more sign-in or key, or only by hand, and the exact manual steps. Show it before asking the person to confirm. While a removal runs, `removal_started_at` is set. Once the domain is removed, it answers `removed: true` with `result`, what the removal did, to the callers that could have removed it: read this, not the connection's `404`, to learn the outcome. An end user's widget token must be bound as for `DELETE /connections/{id}`.","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"The removal plan, or the outcome of a finished removal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemovalPlan"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/certificate":{"get":{"operationId":"getDomainCertificate","summary":"The domain's certificate, its renewal and its history","tags":["Connections"],"description":"The HTTPS certificate the edge holds for the domain, as the edge last reported it: status, issuer, when it was issued and last renewed, when it expires and the next renewal starts, the last error while renewing keeps failing, and the certificate history (issued, renewed, failed, expiring). An apex that redirects www also gets `www_certificate`. Every served domain has one, so this read is not behind the Secure plan feature (the `/ssl` management routes are). `status` is `not_reported` until the edge reports the certificate.\n\nA delegated agent token needs `domains:read`.\n\nA widget token must be the connection's end user: a connection that names another end user than the token's `end_user_ref`, or names one while the token names none, answers `403` `token_wrong_end_user` before anything is read or changed, and a connection that names none is any token's. An API key, an app-scoped token and a delegated agent token are not limited by it.","security":[{"widgetJWT":[]},{"apiKey":[]},{"agentToken":["domains:read"]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"The certificate","content":{"application/json":{"schema":{"type":"object","required":["connection_id","certificate","renewal","history"],"properties":{"connection_id":{"type":"string"},"certificate":{"$ref":"#/components/schemas/CertificateView"},"www_certificate":{"$ref":"#/components/schemas/CertificateView"},"renewal":{"type":"object","properties":{"automatic":{"type":"boolean"},"needs_dns_access":{"type":"boolean","description":"Always false; the edge renews through the domain itself (TLS-ALPN-01 or HTTP-01)."},"retry_every":{"type":"string"},"how":{"type":"string"}}},"history":{"type":"array","items":{"$ref":"#/components/schemas/DomainEvent"}}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/ForbiddenOrWrongEndUser"},"404":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/services":{"get":{"operationId":"getConnectionServices","summary":"The CustomDomain™ services the domain uses","tags":["Connections"],"description":"Every CustomDomain™ service with whether this domain uses it, computed from stored facts: DNS connect (with the rail that wrote the records and the access CustomDomain™ holds), managed DNS, edge serving, the HTTPS certificate, Power, monitoring, automatic repair, redirects, email records and CAA. `state` is `active`, `pending` (set up, not serving yet), `attention` (in use, and something needs a person), `paused` (automatic repair where CustomDomain™ holds the access but the deployment has not switched repair on, `MONITOR_AUTO_REPAIR`) or `inactive`. An end user's widget token (scope `connect`) reads this only when it is bound to the domain and minted with the connection's own `end_user_ref`; use an API key otherwise.","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"The services","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionServices"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/events":{"get":{"operationId":"listConnectionEvents","summary":"The domain's timeline","tags":["Connections"],"description":"What happened to the domain, newest first: certificates issued, renewed, failing and expiring; drift found and what was done about it; access kept and revoked. `kind` narrows it to a prefix (`certificate.`, `drift.`, `access.`); `before` pages back with the previous page's `next_before`. An end user's widget token (scope `connect`) reads this only when it is bound to the domain and minted with the connection's own `end_user_ref`; use an API key otherwise.","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"},{"name":"kind","in":"query","required":false,"schema":{"type":"string"}},{"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":"The events","content":{"application/json":{"schema":{"type":"object","required":["connection_id","domain","events"],"properties":{"connection_id":{"type":"string"},"domain":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/DomainEvent"}},"next_before":{"type":"string","format":"date-time"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/services:summary":{"get":{"operationId":"getServicesSummary","summary":"How many domains use each service, per application and workspace","tags":["Connections"],"description":"For the API key's workspace (or one application with `app_id`), the number of domains using each service, and the number needing attention, in total and per application, and which domains need attention and why.","security":[{"apiKey":[]}],"parameters":[{"name":"app_id","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The counts","content":{"application/json":{"schema":{"type":"object","required":["catalog","workspace","applications","needs_attention","truncated"],"properties":{"catalog":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"workspace":{"type":"object","properties":{"domains":{"type":"integer"},"services":{"type":"object","additionalProperties":{"type":"integer"}},"attention":{"type":"object","additionalProperties":{"type":"integer"}}}},"applications":{"type":"array","items":{"type":"object","properties":{"application_id":{"type":"string"},"name":{"type":"string"},"domains":{"type":"integer"},"services":{"type":"object","additionalProperties":{"type":"integer"}},"attention":{"type":"object","additionalProperties":{"type":"integer"}}}}},"needs_attention":{"type":"array","description":"The domains behind the attention counts, by domain name: one item per service that needs someone, at most 50.","items":{"type":"object","required":["connection_id","application_id","domain","service","name","detail"],"properties":{"connection_id":{"type":"string"},"application_id":{"type":"string"},"domain":{"type":"string"},"service":{"type":"string","description":"The service id, as in catalog."},"name":{"type":"string"},"detail":{"type":"string","description":"What needs doing, for people."}}}},"truncated":{"type":"boolean","description":"True when the workspace has more domains than one summary counts (2000)."}}}}}},"401":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/saved-access":{"get":{"operationId":"getConnectionSavedAccess","summary":"The kept keys that may act for the domain, for you","tags":["Provider accounts"],"description":"$ef","security":[{"widgetJWT":[]},{"apiKey":[]},{"agentToken":["domains:read"]}],"parameters":[{"$ref":"#/components/parameters/Id"},{"name":"provider","in":"query","required":false,"schema":{"type":"string"},"description":"A provider id other than the one detected for the domain."}],"responses":{"200":{"description":"The saved access, best first","content":{"application/json":{"schema":{"type":"object","required":["saved_access"],"properties":{"saved_access":{"type":"array","items":{"$ref":"#/components/schemas/SavedAccess"}}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"description":"An agent token without `domains:read`, a widget token for another domain (`forbidden`), or an end user's token that is bound to no domain (`token_not_bound`) or to another end user than the connection's (`token_wrong_end_user`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/monitor":{"get":{"operationId":"getConnectionMonitor","summary":"What the drift monitor last found for the domain, and what was done","tags":["Monitor"],"description":"$f0","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"The monitoring state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorView"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/connections:lookup":{"get":{"operationId":"lookupConnection","summary":"Find your connection for a domain","tags":["Connections"],"description":"Returns the caller's connection for a domain, for an app that stored the domain but not the connection id (for example to open the removal flow). A connect-scoped widget token must be minted for that domain, and finds a connection that names an end user only when minted with the same `end_user_ref`; an app-scoped token finds any domain of its application, and an API key any domain of its tenant.","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionWithRecords"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}:disconnect":{"post":{"operationId":"disconnectConnectionWithChoice","summary":"Remove a domain, optionally authorizing the record removal once with a key","tags":["Connections"],"description":"The same removal as `DELETE /connections/{id}` with a body. Send `credential` (a DNS provider API key) to authorize removing the records once when we did not keep the access that added them; it is used for this removal and never stored. The zone must show at least one of our records with that key, or the outcome lists the manual steps (the key may belong to another account). Answers `200` with the outcome; an end user's widget token must be bound as for `DELETE /connections/{id}`.\n\nA delegated agent token needs `domains:disconnect` and must send `confirm`, as for `DELETE /connections/{id}`. A share link's token is refused with `403` `forbidden`, as there.","security":[{"widgetJWT":[]},{"apiKey":[]},{"agentToken":["domains:disconnect"]}],"parameters":[{"$ref":"#/components/parameters/Id"},{"name":"confirm","in":"query","required":false,"description":"The domain being removed, as written on the connection (case, scheme, path and a trailing dot do not matter). Required of a delegated agent token: without it the answer is `400 confirmation_required`. Any credential that sends it, an API key or an application token included, gets `409 confirmation_mismatch` when it names another domain (`400 confirmation_required` when it is empty). Nothing is removed either way. A credential other than an agent token may leave it out.","schema":{"type":"string","examples":["shop.acme.com"]}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"records":{"type":"string","enum":["remove","keep"]},"provider":{"type":"string","description":"DNS provider id; defaults to the connection's provider."},"zone":{"type":"string","description":"The DNS zone; found from the key when omitted."},"credential":{"type":"object","properties":{"token":{"type":"string","description":"The provider API key, used once."}}}}}}}},"responses":{"200":{"description":"Removed; what happened to the records","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisconnectResult"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"`reauthorization_required`, `removal_in_progress` or `confirmation_mismatch`, as for `DELETE /connections/{id}`.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["reauthorization_required","removal_in_progress","confirmation_mismatch"]},"plan":{"$ref":"#/components/schemas/RemovalPlan"}}}}}}}}},"/connections/{id}/diagnose":{"get":{"operationId":"diagnoseConnection","summary":"What public DNS shows for each record, and what is left to do","tags":["Connections"],"description":"$f1","security":[{"widgetJWT":[]},{"apiKey":[]},{"agentToken":["domains:read"]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Diagnosis","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionDiagnosis"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/ForbiddenOrWrongEndUser"},"404":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/records":{"get":{"operationId":"getConnectionRecords","summary":"Authoritative desired DNS record set for a connection","tags":["Connections"],"description":"The single source of truth the widget renders, the OAuth callback writes, and the propagation poller verifies. Before records are applied, the default edge record is synthesized server-side.\n\nA delegated agent token needs `domains:read` or `domains:connect`.\n\nA widget token must be the connection's end user: a connection that names another end user than the token's `end_user_ref`, or names one while the token names none, answers `403` `token_wrong_end_user` before anything is read or changed, and a connection that names none is any token's. An API key, an app-scoped token and a delegated agent token are not limited by it.","security":[{"widgetJWT":[]},{"apiKey":[]},{"agentToken":["domains:read"]},{"agentToken":["domains:connect"]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Records","content":{"application/json":{"schema":{"type":"object","required":["connection_id","records"],"properties":{"connection_id":{"type":"string"},"records":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecord"}}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/ForbiddenOrWrongEndUser"},"404":{"$ref":"#/components/responses/Error"}}},"put":{"operationId":"setConnectionRecords","summary":"Supply the connection's desired DNS record set","tags":["Connections"],"description":"Replaces the connection's desired record set with one the INTEGRATOR authored, for records that cannot be derived from the domain; the motivating case is Amazon SES email verification, whose three Easy-DKIM CNAMEs are minted per domain by SES. The supplied set then behaves exactly like ours: the OAuth rail writes it with the customer's provider credential, the widget renders it for manual setup, and the propagation poller verifies it before the connection goes live.\n\nServer-to-server only (API key): a widget JWT lives in a browser and may not choose the records we write into a customer's zone. Hosts are relative to the connection (`@`, `_dmarc`, `sel._domainkey`) and must resolve inside its zone. The Domain Connect rail refuses a connection carrying a supplied set, because that rail applies OUR published templates at the provider, so it cannot write records it did not author.","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["records"],"properties":{"records":{"type":"array","minItems":1,"maxItems":25,"items":{"$ref":"#/components/schemas/DnsRecord"}}}}}}},"responses":{"200":{"description":"The connection's new desired record set","content":{"application/json":{"schema":{"type":"object","required":["connection_id","records_source","records"],"properties":{"connection_id":{"type":"string"},"records_source":{"type":"string","enum":["integrator"]},"records":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecord"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/end-user-email":{"put":{"operationId":"setConnectionEndUserEmail","summary":"Leave the end user's email address on a connection","tags":["Connections"],"description":"The widget's optional \"Get DNS updates by email\" field. After a domain is set up, the end user can leave an address so they hear if its records ever need to change (one email, with the new records, sent on the platform's behalf).\n\nA widget token for the connection's own application can set an address only while the connection has none: when one is already there (the platform's, or an earlier one) the answer is `409`, so a browser can never overwrite what the platform gave. A widget token bound to another end user than the connection's (`end_user_ref`) is refused with `403`: the reconnect email goes to this address and its link signs in as the connection's end user. An API key replaces any earlier address. The address is never echoed back and never logged.\n\nTest domains refuse the call.\n\nA share link's token never sets the address, on any connection: a link is a credential to set one domain up, not the end user, and the address receives the reconnect link that signs in as them.","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","maxLength":254}}}}}},"responses":{"204":{"description":"Stored (or dropped while the feature is off)"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/managed-dns":{"post":{"operationId":"startManagedDNS","summary":"Start managed DNS for a connection's domain","tags":["Managed DNS"],"description":"$f2","security":[{"apiKey":[]},{"widgetJWT":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":false,"description":"No parameters. Send no body, or `{}`.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"responses":{"200":{"description":"Managed DNS was already started; the zone as it stands.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedDNSView"}}}},"201":{"description":"The zone was created and filled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedDNSView"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"description":"`forbidden` (the application does not offer DNS hosting on CustomDomain™, or a role that cannot write connections), `token_wrong_end_user` (a widget token: the connection belongs to another end user; mint a token with this domain's `end_user_ref`), or `workspace_suspended` (see the `ForbiddenOrSuspended` response).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"The domain's zone is already hosted for another account, or (for a widget token) for someone else: not every connection linked to it is the token's (another end user's, the platform's for another name, another application's), or none is linked. Or another change to it is in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`managed_dns_unavailable` (this domain can't be hosted; `details` says why) or `managed_dns_limit` (the account's zone limit).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`managed_dns_backend_error`: the DNS hosting service didn't respond. Nothing is lost; call again to finish.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"getManagedDNS","summary":"The connection's managed DNS zone","tags":["Managed DNS"],"description":"The hosted zone's status, the nameservers to set at the registrar, what the registry currently lists, the registrar, every record, and notes to show the user. Poll it while `status` is `awaiting_delegation`. 404 when managed DNS was never started for this connection. A widget token reads it only for its own end user's connection and only when the zone is that end user's (every connection linked to it is the token's, as for the start above); otherwise it gets 403 or 409 and none of the zone.","security":[{"apiKey":[]},{"widgetJWT":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"The zone","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedDNSView"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"description":"`token_wrong_end_user`: a widget token whose end user is not the connection's (mint a token with this domain's `end_user_ref`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"A widget token only: the zone is hosted for someone else, because not every connection linked to it is the token's.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/managed-dns/records":{"post":{"operationId":"addManagedDNSRecords","summary":"Import a zone file or add records to the managed zone","tags":["Managed DNS"],"description":"Send exactly one of `zone_file` (a BIND zone file, at most 256 KB) or `records` (at most 500). Records from a zone file are `imported`: for every name and type the file defines, they replace what discovery found. Listed records are `manual` and are added alongside what is there. Records CustomDomain™ needs for the connection always win: an imported record that collides with one is skipped with a note, and a listed one is refused with 409. Zone file lines that can't be hosted (SOA, the zone's own NS set, unsupported types, names outside the zone) are skipped, each with a warning naming its line. A zone holds at most 500 records.\n\nOnce the zone is `active`, only an API key or an app-scoped widget token may change it; an end user's connect-scoped token may change the zone only during setup, and only a zone that is its own: its connection's end user and every connection linked to the zone are the token's (as for the start above).","security":[{"apiKey":[]},{"widgetJWT":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedDNSRecordsRequest"}}}},"responses":{"200":{"description":"The zone after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedDNSView"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"description":"`token_wrong_end_user` (a widget token whose end user is not the connection's), or `forbidden` (the zone is live and the token is an end user's: use an API key or an app-scoped token).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"A listed record would override one CustomDomain™ needs for the connection, or (a widget token) the zone is hosted for someone else because not every connection linked to it is the token's.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"$ref":"#/components/responses/Error"},"422":{"description":"`invalid_zone_file` (nothing in the file can be hosted) or `too_many_records` (the zone would pass 500 records).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/managed-dns/records/{record_id}":{"delete":{"operationId":"deleteManagedDNSRecord","summary":"Remove one record from the managed zone","tags":["Managed DNS"],"description":"Removes a `discovered`, `imported` or `manual` record. A `customdomain` record is how CustomDomain™ serves the domain and is refused with 409; disconnecting the domain removes it. Once the zone is `active`, only an API key or an app-scoped widget token may remove records. A widget token removes records only from a zone that is its own, as for adding them.","security":[{"apiKey":[]},{"widgetJWT":[]}],"parameters":[{"$ref":"#/components/parameters/Id"},{"name":"record_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The zone after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedDNSView"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"description":"`token_wrong_end_user` (a widget token whose end user is not the connection's), or `forbidden` (the zone is live and the token is an end user's).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"The record is one CustomDomain™ needs for the connection, or (a widget token) the zone is hosted for someone else because not every connection linked to it is the token's.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/nameservers":{"get":{"operationId":"getNameserverMigration","summary":"The connection's latest nameserver migration","tags":["Nameservers"],"description":"The newest nameserver migration started for the connection's domain: its state, the old and new nameservers, what the registry lists now, what it waits on (`waiting_for`) and what a person does next (`next_step`) and, when something has to be pressed, which request presses it (`next_action`: `sign_in` while the move waits for the cloud browser, `retry` after a stop that changed nothing at the registrar (its `body` names the move's `path`, and for `api` its connected account, so posting it repeats the same move), `rollback` after a stop that did; `null` when nothing is waiting for a press). Poll it while the state is not `active`, `failed` or `rolled_back`. 404 when no migration was started for this connection. Authorized like the other connection routes: an API key within the tenant, or a widget token of the connection's own application and end user (a connection that names another end user answers 403 `token_wrong_end_user`). A delegated agent token needs `domains:read`.","security":[{"apiKey":[]},{"widgetJWT":[]},{"agentToken":["domains:read"]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"The migration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NameserverMigration"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"description":"`token_wrong_end_user`: a widget token whose end user is not the connection's (mint a token with this domain's `end_user_ref`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/nameservers:offer":{"get":{"operationId":"getNameserverOffer","summary":"Whether the domain's nameservers can move now, and how","tags":["Nameservers"],"description":"$f3","security":[{"apiKey":[]},{"widgetJWT":[]},{"agentToken":["domains:read"]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"The offer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NameserverStartOffer"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"description":"`forbidden` (an end user's widget token), a connection of another application (a delegated agent token), or `workspace_suspended` (see the `ForbiddenOrSuspended` response).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/nameservers:migrate":{"post":{"operationId":"migrateNameservers","summary":"Move the domain's nameservers, with the end user's consent","tags":["Nameservers"],"description":"$f4","security":[{"apiKey":[]},{"widgetJWT":[]},{"agentToken":["domains:connect"]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NameserverMigrateRequest"}}}},"responses":{"200":{"description":"The domain's open migration, resumed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NameserverMigration"}}}},"201":{"description":"A migration was created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NameserverMigration"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"description":"`forbidden` (the credential may not do this: a widget token that sends `target`, a key or the zone flags, the setting is off, a role that cannot write connections, a `provider_account_id` the caller may not use because another member connected it, or a key for other domains or another application), `token_wrong_end_user` (a widget token whose end user is not the call's connection's or the open move's connection's, or the open move names no connection: mint a token with this domain's `end_user_ref`), `target_not_allowed` (an agent token), or `workspace_suspended` (see the `ForbiddenOrSuspended` response).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"The domain already uses these nameservers, its nameservers are being moved for another account (or, for a delegated agent token or a widget token, for another application of the workspace), its managed zone is hosted for someone else (a widget token with target `managed`: not every connection linked to the zone is the token's), or another change to the migration is in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`nameserver_migration_unavailable` (this domain's nameservers can't be moved; `details` says why), `nameserver_api_unsupported` (the registrar has no API call that changes nameservers), `nameserver_agent_unavailable` (path `agent` asked for, but the cloud browser can't change this registrar's nameservers), `registrar_locks_nameservers` (the domain is registered at a registrar that requires its own nameservers, Cloudflare Registrar), `registrar_mismatch` (the key or account is at another company than the registrar RDAP names), `zone_host_unsupported` or `dns_host_not_configured`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/nameservers:rollback":{"post":{"operationId":"rollbackNameservers","summary":"Move the domain's nameservers back","tags":["Nameservers"],"description":"$f5","security":[{"apiKey":[]},{"widgetJWT":[]},{"agentToken":["domains:connect"]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NameserverRollbackRequest"}}}},"responses":{"200":{"description":"The migration, rolled back.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NameserverMigration"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"description":"`token_wrong_end_user` (a widget token whose end user is not the connection's), or `forbidden` (a widget token sends a key, or a credential that may not do this, or `provider_account_id` names an account the caller may not use: another member's).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"`old_dns_gone`: the old nameservers no longer answer for the zone; move back to the registrar's own DNS instead. `changed_elsewhere`: the registrar lists other nameservers than the move's, so a move back would overwrite someone else's change. Or nothing was changed at the registrar to move back.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`registrar_mismatch`: `provider_account_id` names an account at another company than the registrar the move named; nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`registrar_refused`: the registrar did not accept the old nameservers; they were read back and nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/Error"},"504":{"description":"`registrar_unconfirmed`: the registrar's answer was lost and it could not be read back, so whether the move back happened is not known. Nothing is recorded, but the move stays stopped (its checks end), so nothing sends the new nameservers again meanwhile; try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/connections/{id}/grant":{"delete":{"operationId":"disableManagedConnection","summary":"Turn managed mode OFF without disconnecting","tags":["Connections"],"description":"Drops the stored grant (async one-click, or a kept provider sign-in, which is also revoked at the provider where it allows it) and clears the connection's `managed` flag, leaving the connection and its applied records in place. The records the provider already wrote stay live; the control plane simply stops holding a credential to re-apply / revert them. This is **not** `DELETE /v1/connections/{id}` (which reverts the template at the provider and removes the whole connection). Idempotent: a connection that is already unmanaged returns `200`.\n\nA widget token must be the connection's end user: a connection that names another end user than the token's `end_user_ref`, or names one while the token names none, answers `403` `token_wrong_end_user` before the grant is touched, and a connection that names none is the token's as before. An API key and an app-scoped token are not limited by it.","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Managed mode disabled (grant dropped, managed=false, connection kept)","content":{"application/json":{"schema":{"type":"object","required":["connection_id","managed"],"properties":{"connection_id":{"type":"string"},"managed":{"type":"boolean","enum":[false]}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"description":"`token_wrong_end_user` (a widget token: the connection names another end user, or names one while the token names none; the grant is kept and nothing is changed) or `forbidden` (a role that cannot write connections).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/apply":{"post":{"operationId":"applyConnection","summary":"Write a connection's records through the customer's provider (BYO token, used once)","tags":["Connections"],"description":"**Rail B (API-token apply).** The scoped provider credential is used once to write the records and is never stored. The connection advances to `propagating`; the poller promotes it to `live` once the records appear in public DNS.\n\nA widget JWT applies to its own application's connections (a domain-bound token to its own domain only). An API key applies to a connection of any application in its tenant; a member's key needs a role that operates apps (not viewer).\n\nA widget token must be the connection's end user: a connection that names another end user than the token's `end_user_ref`, or names one while the token names none, answers `403` `token_wrong_end_user` before anything is read or changed, and a connection that names none is any token's. An API key, an app-scoped token and a delegated agent token are not limited by it.","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["credential","records"],"properties":{"provider":{"type":"string","description":"DNS provider id; defaults to the detected provider."},"zone":{"type":"string","description":"DNS zone the credential manages; defaults to the connection domain."},"credential":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"Scoped provider API token; used once, never persisted."}}},"records":{"type":"array","items":{"$ref":"#/components/schemas/WritableRecord"}}}}}}},"responses":{"200":{"description":"Applied","content":{"application/json":{"schema":{"type":"object","properties":{"connection":{"$ref":"#/components/schemas/Connection"},"records":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecord"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/ForbiddenSuspendedOrWrongEndUser"},"404":{"$ref":"#/components/responses/Error"},"422":{"description":"The provider refused the credential (`ProviderAuthenticationError`) or the write (`dns_write_failed`), or, at Porkbun, the domain is not opted in to API access (`porkbun_api_access_disabled`: the account holder switches on API Access for the domain in Porkbun's Domain Management, then tries again)"},"503":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}:reapply":{"post":{"operationId":"reapplyConnection","summary":"Re-apply a managed connection's desired records (async one-click, no re-consent)","tags":["Connections"],"description":"$f6","security":[{"widgetJWT":[]},{"apiKey":[]},{"agentToken":["domains:connect"]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Re-applied (records updated). NOTE: this is a re-apply RECEIPT, not a connection object; it carries `connection_id` rather than the connection's own `id`, and none of the other connection fields. Fetch `GET /connections/{id}` if you need the connection itself.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReapplyResult"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"description":"`token_wrong_end_user` (a widget token: the connection names another end user, or names one while the token names none; nothing is written), `forbidden`, or `workspace_suspended` (see the `ForbiddenOrSuspended` response).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"The connection is not managed, has no stored grant, or the grant was revoked (re-consent required); or a provider account keeps it and CustomDomain™ did not write its records, or the account holds no usable key"},"422":{"description":"The provider refused the provider account's key (`ProviderAuthenticationError`) or the write (`dns_write_failed`)"},"503":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}:recheck":{"post":{"operationId":"recheckConnection","summary":"Check a connection's DNS now, and report what public DNS answered","tags":["Connections"],"description":"$f7","security":[{"widgetJWT":[]},{"apiKey":[]},{"agentToken":["domains:connect"]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"The connection after the check, plus what the check found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecheckResult"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"description":"`token_wrong_end_user` (a widget token: the connection names another end user, or names one while the token names none; nothing is changed) or `forbidden` (an agent token without `domains:connect`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"A failed connection cannot be retried because the same application already has another active connection for this domain; retry that one instead"}}}},"/connections/{id}:reconnect-link":{"post":{"operationId":"createConnectionReconnectLink","summary":"A link the end user opens to renew the domain's lasting API key","tags":["Cloud browser"],"description":"$f8","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"send":{"type":"boolean","description":"Email the link to the end user when their address is known."}}}}}},"responses":{"200":{"description":"The link, or that it was emailed.","content":{"application/json":{"schema":{"type":"object","required":["emailed"],"properties":{"link":{"type":"string","format":"uri","description":"The reconnect link; absent when it was emailed."},"emailed":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}:use-saved-access":{"post":{"operationId":"useConnectionSavedAccess","summary":"Write the domain's records with a kept key","tags":["Provider accounts"],"description":"$f9","security":[{"apiKey":[]},{"widgetJWT":[]},{"agentToken":["domains:connect"]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["account_id"],"properties":{"account_id":{"type":"string"}}}}}},"responses":{"200":{"description":"The domain's outcome and the account after it","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"$ref":"#/components/schemas/AccountConnectResult"},"account":{"$ref":"#/components/schemas/ProviderAccount"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/ReachQuota"},"500":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}:retarget":{"post":{"operationId":"retargetConnection","summary":"Move a domain to its application's current routing, or back to the edge","tags":["Connections"],"description":"$fa","security":[{"apiKey":[]},{"agentToken":["domains:connect"]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","enum":["application","edge"],"default":"application","description":"Where to move the domain."}}}}}},"responses":{"200":{"description":"The domain's routing after the move, and its records from now on.","content":{"application/json":{"schema":{"type":"object","required":["connection_id","moved","routing","records","customer_action_required","stops_edge_serving"],"properties":{"connection_id":{"type":"string"},"moved":{"type":"boolean"},"routing":{"$ref":"#/components/schemas/ConnectionRouting"},"previous_routing":{"$ref":"#/components/schemas/ConnectionRouting"},"records":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecord"}},"customer_action_required":{"type":"boolean"},"rewriting":{"type":"boolean","description":"CustomDomain™ is writing the new records itself, through the rail that wrote the old ones. Present only when true; `customer_action_required` is then false."},"stops_edge_serving":{"type":"boolean"},"status":{"$ref":"#/components/schemas/ConnectionStatus","description":"The domain's status after the move."}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/oauth:start":{"post":{"operationId":"startConnectionOAuth","summary":"Begin the sign-in to the DNS provider for a connection","tags":["Connections"],"description":"$fb","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["return_origin"],"properties":{"provider":{"type":"string","description":"DNS provider id; defaults to the detected provider."},"return_origin":{"type":"string","description":"Web origin the callback page may postMessage the outcome to; must be on the server's allowlist."},"region":{"type":"string","enum":["eu","ca","us"],"description":"OVHcloud only: the API region the user's OVHcloud account lives in (default `eu`). The domain check's `rails.oauth.regions` lists the regions this deployment offers."},"purpose":{"type":"string","enum":["connect","remove"],"default":"connect","description":"`remove` signs in once more to remove the records we added (and put back what they replaced) for a connection whose access we did not keep, then disconnects the domain, as `GET /connections/{id}/removal` offers when its `record_removal` is `reauthorize`. The sign-in is used for the removal and withdrawn; it is never kept. The callback's message carries `purpose: \"remove\"` and the `records` outcome, and `GET /connections/{id}/removal` answers it once the domain is gone. An end user's widget token must be bound as for `DELETE /connections/{id}`."},"access":{"type":"string","enum":["continuous","one_time"],"description":"The person's choice for a connect. `continuous` keeps the sign-in, encrypted, so we can put back records that disappear and remove them when the domain is removed; offered only where the deployment can keep this provider's sign-in (`rails.oauth.managed` on the domain check). `one_time` uses it for this write and drops it. Omitted, the deployment's default applies (kept where it can be)."},"new_sign_in":{"type":"boolean","description":"\"Use another account.\" A connect sign-in for a domain that a saved key may already act for (`GET /connections/{id}/saved-access`) is refused with `409` `saved_access_available`, before anything is started; `true` signs in anyway. Never needed by an end user's widget token, which is never refused (it may be offered its own key by the domain check, but that is not a refusal yet)."}}}}}},"responses":{"200":{"description":"The URL to open, and what it runs","content":{"application/json":{"schema":{"type":"object","required":["authorize_url","provider","flow"],"properties":{"authorize_url":{"type":"string","format":"uri"},"provider":{"type":"string"},"flow":{"type":"string","enum":["oauth2","vercel_integration","porkbun_handoff","porkbun_dnsconnect","ovh_consent","mcp_oauth"]},"managed":{"type":"boolean","description":"The connect will keep its credential (managed mode)."},"access":{"type":"string","enum":["continuous","one_time"],"description":"What will happen to the credential after the sign-in."},"purpose":{"type":"string","enum":["remove"],"description":"Present for a removal sign-in."},"callback_origin":{"type":"string","description":"Origin the result will be postMessaged from; check `MessageEvent.origin` against it."},"region":{"type":"string","description":"OVHcloud only, the region the consent was requested in."}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/ForbiddenSuspendedOrWrongEndUser"},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"`saved_access_available`: a connect sign-in for a domain that a saved key may already act for. Use it (`POST /connections/{id}:use-saved-access`), or send `new_sign_in: true` to sign in with another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`provider_rate_limited`: the provider refused to start another sign-in from our servers for now (Porkbun allows 20 key requests an hour per IP address); `details` says when to retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`provider_unavailable`: the provider did not start the sign-in (Porkbun key request, OVHcloud consumer key request).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/browser:start":{"post":{"operationId":"startConnectionBrowser","summary":"Begin the cloud browser sign in for a connection","tags":["Cloud browser"],"description":"$fc","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider","return_origin","consent_version"],"properties":{"provider":{"type":"string","description":"DNS provider id; defaults to the detected provider."},"return_origin":{"type":"string","description":"Web origin the popup posts its result to; must be on the server's allowlist."},"consent_version":{"type":"string","enum":["cb-1","cb-2","cb-3","cb-4"],"description":"The id of the consent text the customer was shown, stored with the session. Only an id that was ever issued is accepted (`cb-1` and `cb-2` the widget's earlier consent lines, `cb-3` the popup's own sign in form, `cb-4` the kept key notice); any other id is refused with `422` `consent_unknown`. A value that is not shaped like an id (1 to 32 of `[A-Za-z0-9._-]`) is a `400`."},"locale":{"type":"string","description":"The language the popup reads in, a plain code such as `en`. Defaults to `en`."},"purpose":{"type":"string","enum":["","nameservers"],"description":"`nameservers` starts the session for the connection's nameserver migration (path `agent`) instead of its records: the plan is to turn DNSSEC off, or to set the exact new nameservers, and the agent may open only those controls. Refused with `409` unless the migration is waiting for a sign in (`waiting_for: browser_session`). Empty or omitted: the records."},"viewport_hint":{"type":"object","description":"Optional. The size of the popup's live area, so the provider's sign in page fills it at full size. The remote browser is created at this width when it is a whole number from 360 to 720 and at this height when it is a whole number from 480 to 800; a side outside its range is ignored and the provider's default is used for it. The desktop popup (680 by 760) sends 695 by 716. Leave it out for the default.","properties":{"width":{"type":"integer","minimum":360,"maximum":720,"description":"Whole CSS pixels, 360 to 720: the live area's width plus the remote page's scrollbar, which the popup clips."},"height":{"type":"integer","minimum":480,"maximum":800,"description":"Whole CSS pixels, 480 to 800."}}},"mode":{"type":"string","enum":["connect","reconnect"],"description":"`connect` (the default) connects the domain. `reconnect` renews the lasting API key CustomDomain™ made for this connection, for the key's own provider, and changes no DNS record; the session ends `done` when the new key is in place."},"new_sign_in":{"type":"boolean","description":"\"Use another account.\" A connect for a domain that a saved key may already act for (`GET /connections/{id}/saved-access`) is refused with `409` `saved_access_available`, before a session row exists or a browser is paid for; `true` signs in anyway. A reconnect and a nameserver session are never refused, and neither is an end user's widget token."},"widget_session_id":{"type":"string","description":"Optional. The widget's own session id (the `session_id` of its funnel beacons, 8 to 64 of `[A-Za-z0-9_-]`). It is recorded on the cloud browser session and the widget session of the same application is linked to it, so a sign in's outcome can be read against the device and place it ran for. It changes nothing about the session; a value that is not a session id is ignored."}}}}}},"responses":{"200":{"description":"The session was created.","content":{"application/json":{"schema":{"type":"object","required":["session_id","open_url","vendor","expires_at"],"properties":{"session_id":{"type":"string","description":"The session id, `bs_` and 32 hex characters."},"open_url":{"type":"string","format":"uri","description":"The popup page, with `#c=&l=` in its fragment."},"vendor":{"type":"string","description":"The browser hosting company the session runs on, shown to the customer: `Browserbase`, or `Kernel` for a provider whose sign in runs there (Network Solutions)."},"expires_at":{"type":"string","format":"date-time","description":"The latest the session can end."}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"description":"`browser_customer_present_only` (an agent, the MCP server, a plain API key, a request with no `Origin` header, or an `Origin` that is not on the return origin allowlist), `token_not_bound` (the widget token is bound to no domain, or only to other domains: mint one with `domain` and `end_user_ref`; the domain check gave this caller the same word in `rails.cloud_browser.reason`), `token_wrong_end_user` (the widget token is bound to the domain but another end user connected it: mint one with this domain's `end_user_ref`), `forbidden` (a role that cannot write connections), `browser_provider_not_allowed` (the rail is not offered for this provider or workspace, or the provider has a sign in of its own), or `workspace_suspended` (CustomDomain™ support suspended the workspace; see the `ForbiddenOrSuspended` response). The `title` of a `token_not_bound` or `token_wrong_end_user` answer is a plain line for the person; `details` says what to mint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"`browser_session_active`: a secure sign in is already running for this domain, `browser_reconnect_unavailable`: `mode: reconnect` for a connection that has no lasting API key CustomDomain™ made, or whose provider cannot make one now, or `saved_access_available`: a kept key can already act for this domain (see `new_sign_in`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`browser_unsupported_records`: the record set cannot be written through the provider's page. `types` names what is in the way. `consent_unknown`: `consent_version` is shaped like an id but is not one that was ever issued (`cb-1` to `cb-4`); nothing was started.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"types":{"type":"array","items":{"type":"string"}}}}]}}}},"429":{"description":"`browser_rate_limited`: too many starts for this domain or workspace. `Retry-After` says when the window turns.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until a new start is allowed."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`browser_unavailable` (not configured, switched off or paused), `browser_busy` (the browser vendor answered that it is busy right now; try again after `Retry-After`) or `browser_capacity` (the vendor is not answering, or a limit of sessions or monthly minutes is reached). Offer the manual steps.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait; present for `browser_busy` and for a vendor that is not answering."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/connections/{id}/browser:resume":{"post":{"operationId":"resumeConnectionBrowser","summary":"Hand the cloud browser sign in to a new popup","tags":["Cloud browser"],"description":"**Customer present only.** The customer left the popup to read a code in their mail app and the phone threw it away, or closed the window by mistake, while the session still waits on them. This hands the SAME session (the same remote browser, still on the provider's page) to a new popup: the answer is the one of `browser:start`, with a new single use bootstrap code in the popup's address, and the previous popup's session token stops working at once. One popup at a time.\n\nAllowed only while the session waits on the customer: about to sign in, signing in (a code prompt included), or while the agent has handed the page back. It takes the gate of `browser:start` (an end user's widget token bound to the domain and the end user, or the console, and an `Origin` on the return origin allowlist), and only the caller that started the session may resume it: the same end user's widget token, or the console. Anyone else, an API key included, gets `browser_not_waiting`. A session takes a few, one every few seconds.","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"locale":{"type":"string","description":"The language the new popup reads in, a plain code such as `en`. Defaults to the session's."},"session_id":{"type":"string","description":"The session the caller last held. When present and the connection's waiting session is another one, the answer is `409 browser_not_waiting`, and the caller starts a new sign in."},"return_origin":{"type":"string","description":"The caller's origin, as for `browser:start`. When present it must be an allowed origin; the session keeps the origin it started with."},"viewport_hint":{"type":"object","description":"Accepted for symmetry with `browser:start` and not used; the session keeps its size.","properties":{"width":{"type":"integer"},"height":{"type":"integer"}}}}}}}},"responses":{"200":{"description":"The session was handed to a new popup.","content":{"application/json":{"schema":{"type":"object","required":["session_id","open_url","vendor","expires_at"],"properties":{"session_id":{"type":"string","description":"The same session id the start answered."},"open_url":{"type":"string","format":"uri","description":"The popup page, with `#c=&l=` in its fragment."},"vendor":{"type":"string","description":"The browser hosting company the session runs on, shown to the customer: `Browserbase`, or `Kernel` for a provider whose sign in runs there (Network Solutions)."},"expires_at":{"type":"string","format":"date-time","description":"The latest the session can end now."}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"description":"`browser_customer_present_only`, `token_not_bound`, `token_wrong_end_user` and `forbidden` (as for `browser:start`), or `workspace_suspended`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"`browser_not_waiting`: no secure sign in for this domain is waiting on the customer (none is running, or the agent or a change is working).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`browser_expired`: the session ran out of time.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`browser_rate_limited`: resumed a moment ago (`Retry-After`), or too many times for one session (start again).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/browser-sessions:redeem":{"post":{"operationId":"redeemBrowserSession","summary":"Trade the bootstrap code for the session token","tags":["Cloud browser"],"description":"The popup page calls this once, with the code from its address fragment. The code lives two minutes and works once; a second redemption answers `410 browser_link_used`. The `Origin` header must be on the server's return origin allowlist (a browser sends it; a request with none is refused with `browser_customer_present_only`). The token it returns lives in the popup's memory only.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}}}},"responses":{"200":{"description":"The session token and the first view.","content":{"application/json":{"schema":{"type":"object","required":["session_id","token","view"],"properties":{"session_id":{"type":"string"},"token":{"type":"string","description":"The session token. A bearer: never log it or store it."},"view":{"$ref":"#/components/schemas/BrowserSessionView"}}}}}},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"410":{"description":"`browser_link_used` (already redeemed) or `browser_expired` (the code ran out, or the session ended).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/browser-sessions/{sid}":{"get":{"operationId":"getBrowserSession","summary":"Read a cloud browser session","tags":["Cloud browser"],"description":"$fd","security":[{"browserSession":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/BrowserSessionId"}],"responses":{"200":{"description":"The session as the popup may see it, or an account sign in's state for the console.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BrowserSessionView"},{"$ref":"#/components/schemas/AccountSignInSession"}]}}}},"401":{"description":"`browser_expired`: the token is wrong, expired, or for another session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/browser-sessions/{sid}:signed-in":{"post":{"operationId":"signedInBrowserSession","summary":"The customer says they are signed in","tags":["Cloud browser"],"description":"Allowed only in `awaiting_sign_in`. The control plane attaches to the browser, opens the provider's DNS page, reads it (read only) and builds the plan. If the browser is still on the sign in page the state returns to `awaiting_sign_in` with the notice `not_signed_in`. Poll the view for the outcome.","security":[{"browserSession":[]}],"parameters":[{"$ref":"#/components/parameters/BrowserSessionId"}],"responses":{"202":{"description":"Checking.","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["checking"]}}}}}},"401":{"$ref":"#/components/responses/Error"},"409":{"description":"`browser_wrong_state`: the session is not awaiting sign in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`browser_expired`: the sign in window ran out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/browser-sessions/{sid}:approve":{"post":{"operationId":"approveBrowserSession","summary":"Approve the exact plan","tags":["Cloud browser"],"description":"Works once, only in `plan_ready`, only within the approval window (180 seconds), and only with the exact current plan hash. A wrong hash writes nothing. If the records changed after the plan was made, the session returns to `checking` with a fresh plan and a new hash.","security":[{"browserSession":[]}],"parameters":[{"$ref":"#/components/parameters/BrowserSessionId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["plan_hash"],"properties":{"plan_hash":{"type":"string","description":"All 64 hex characters of the plan hash on screen."}}}}}},"responses":{"202":{"description":"Applying.","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["applying"]}}}}}},"401":{"$ref":"#/components/responses/Error"},"409":{"description":"`browser_plan_mismatch` (not the current plan) or `browser_wrong_state` (not in `plan_ready`, or already approved).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`browser_expired`: the approval window ran out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/browser-sessions/{sid}:cancel":{"post":{"operationId":"cancelBrowserSession","summary":"End the session and release the browser","tags":["Cloud browser"],"description":"Idempotent: a session that is already over answers its own state. During `applying` it stops at the next change boundary, never inside a change. A `navigator.sendBeacon` cannot set headers, so this route (and `:event`) also accepts the token in the body, as `{\"token\": \"...\"}` with a content type of `text/plain` or JSON.\n\nThe member who started an account sign in may also cancel it with an API key, on the console's signed visitor forward, in any state before its end: this is how a sign in is abandoned at the list of domains. The key the session made, if any, is dropped and named as `left_key` (the name it was made with and the provider's page that deletes it); the answer carries it. While a keep step is storing the key it is `409` `browser_wrong_state`. The identity rules are those of the read above, and an API key without the console's forward is read as the popup's (`401`).","security":[{"browserSession":[]},{"apiKey":[]},{}],"parameters":[{"$ref":"#/components/parameters/BrowserSessionId"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"The session token, when it cannot be sent as a header."}}}},"text/plain":{"schema":{"type":"string"}}}},"responses":{"200":{"description":"The state the session is in.","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string"},"left_key":{"$ref":"#/components/schemas/LeftKey"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/browser-sessions/{sid}:keep":{"post":{"operationId":"keepBrowserSessionAccount","summary":"Confirm the domains and keep the key of an account sign in","tags":["Provider accounts"],"description":"$fe","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/BrowserSessionId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"`scope` is required to add an account; a sign in that renews one takes no field.","properties":{"scope":{"type":"string","enum":["all","selected"]},"domains":{"type":"array","maxItems":500,"items":{"type":"string"},"description":"With `selected`: at least one domain the key lists. With `all`: none."},"access":{"type":"string","enum":["continuous","one_time"],"default":"continuous"},"application_ids":{"type":"array","maxItems":100,"items":{"type":"string"},"description":"The whole set of other applications the key is shared with. Left out, a new account is shared with none and an existing one keeps its shares."}}}}}},"responses":{"200":{"description":"The key was swapped into an account that already existed: the one the workspace held for this provider account, or the one a renewal sign in is for.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountKept"}}}},"201":{"description":"The account was made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountKept"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"422":{"description":"`domain_not_listed`, `use_once_credential`, `serves_every_application`, or for a renewal `different_account` (the key is another provider account's) or `account_not_verifiable` (nothing to compare the key with).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainsRefusedError"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/browser-sessions/{sid}:finish-manual":{"post":{"operationId":"finishManualBrowserSession","summary":"The customer finished by hand","tags":["Cloud browser"],"description":"Allowed only in `manual_assist`, where the script stopped and the customer adds the records themselves. The session ends and its browser is released; the connection stays `pending` and the propagation poller finishes it when the records appear.","security":[{"browserSession":[]}],"parameters":[{"$ref":"#/components/parameters/BrowserSessionId"}],"responses":{"200":{"description":"Done by hand.","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["done_manual"]}}}}}},"401":{"$ref":"#/components/responses/Error"},"409":{"description":"`browser_wrong_state`: the session is not in manual assist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`browser_expired`: the session ran out of time.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/browser-sessions/{sid}:event":{"post":{"operationId":"browserSessionEvent","summary":"Report a step of the sign in window","tags":["Cloud browser"],"description":"The popup reports one step of its window, for the sign in funnel: the sheet shown, a code or push prompt, a social sign in card, the typing overlay, the hand back for a password, the manual steps taken, the window closed. The control plane records it with the states it writes itself and counts it per provider. It changes nothing about the session and is not a heartbeat. `detail` is one short word (an `sms`, a `google`), never anything the customer typed, a page, an address or a URL: the closed alphabet refuses a space, a slash, a question mark, an equals sign and an at sign. A session that has ended still takes a step (the window closes after the end) while it answers its last view. At most 30 steps a minute per session. A `navigator.sendBeacon` cannot set headers, so, as for `:cancel`, the token may come in the body as `token` with a content type of `text/plain` or JSON.","security":[{"browserSession":[]},{}],"parameters":[{"$ref":"#/components/parameters/BrowserSessionId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrowserSessionEvent"}},"text/plain":{"schema":{"type":"string","description":"The same JSON object, sent by `navigator.sendBeacon`."}}}},"responses":{"204":{"description":"Recorded."},"400":{"description":"`invalid_request`: the body is not the object above, the step is not one of the list, or the detail is not a short word.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`browser_expired`: the token is wrong, expired, or for another session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"429":{"description":"`browser_rate_limited`: more than 30 steps in a minute for this session.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the next step is taken."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/browser-sessions/{sid}:viewport":{"post":{"operationId":"browserSessionViewport","summary":"Tell the server the popup's new size","tags":["Cloud browser"],"description":"The popup's live area after a resize, a turn or full screen, in CSS pixels. Each side is clamped to 320 to 1600 wide and 400 to 1200 high and divided by the scale the session shows the provider's page at (the provider's fit for the kind of device the popup started as), and the page the customer sees is set to that size (device scale factor 1, not mobile) after a read that says the page is not loading; the view's `signals.viewport` reports it once it took, and `sign_in_viewport` is the new size. Allowed only while the customer is in control: signing in (a code or link wait included) or a page the agent handed back. At most 6 a minute per session; send one when a resize has settled.","security":[{"browserSession":[]}],"parameters":[{"$ref":"#/components/parameters/BrowserSessionId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["w","h"],"properties":{"w":{"type":"integer","minimum":0,"maximum":99999,"description":"The live area's width; clamped to 320..1600."},"h":{"type":"integer","minimum":0,"maximum":99999,"description":"The live area's height; clamped to 400..1200."}}}}}},"responses":{"202":{"description":"The size the page is set to.","content":{"application/json":{"schema":{"type":"object","required":["viewport"],"properties":{"viewport":{"$ref":"#/components/schemas/BrowserViewport"}}}}}},"400":{"description":"`invalid_request`: the body is not `{w, h}` with two whole numbers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`browser_expired`: the token is wrong, expired, or for another session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"`browser_wrong_state`: the agent has the page; the customer is not in control.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`browser_expired`: the session ran out of time.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`browser_rate_limited`: more than 6 in a minute for this session.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the next one is taken."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/browser-sessions/{sid}:switch-account":{"post":{"operationId":"switchAccountBrowserSession","summary":"Sign in with another account","tags":["Cloud browser"],"description":"The customer signed in to the provider with an account that does not hold the domain (the view says `wrongAccount`), and tries another one. Allowed only then. The control plane signs the cloud browser out of the provider in the background (the provider's own sign out page, then the browser forgets the provider's cookies and storage, never a social sign in's) and opens the provider's sign in again; meanwhile the view says `notice` `switching_account` and takes no input. The sign in window starts again; the hard cap does not move. At most three accounts are tried: the third that does not hold the domain ends the session (`failed`, `error.code` `browser_wrong_account`), and so does a sign out that fails. No body.","security":[{"browserSession":[]}],"parameters":[{"$ref":"#/components/parameters/BrowserSessionId"}],"responses":{"202":{"description":"Signing out; the sign in follows.","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["awaiting_sign_in"]}}}}}},"401":{"description":"`browser_expired`: the token is wrong, expired, or for another session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"`browser_wrong_state`: the session is not waiting for a choice of account (no `wrongAccount` in the view), or is signing out already.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`browser_expired`: the session ran out of time.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`browser_rate_limited`: switched less than ten seconds ago.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until it is taken again."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/browser-sessions/{sid}:idp":{"post":{"operationId":"idpBrowserSession","summary":"Sign in with an identity provider through the vendor's managed sign in","tags":["Cloud browser"],"description":"$ff","security":[{"browserSession":[]}],"parameters":[{"$ref":"#/components/parameters/BrowserSessionId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider"],"properties":{"provider":{"type":"string","enum":["google","apple"],"description":"The identity provider."}}}}}},"responses":{"202":{"description":"The step started; the view's `idp` says where it stands.","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["awaiting_sign_in"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"description":"`browser_expired`: the token is wrong, expired, or for another session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"`browser_wrong_state`: the session is not waiting for the customer, a step is running, or this sign in is not offered for the provider.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`browser_expired`: the session ran out of time.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/browser-sessions/{sid}:idp-cancel":{"post":{"operationId":"idpCancelBrowserSession","summary":"Leave the identity provider's sign in for the provider's own form","tags":["Cloud browser"],"description":"Ends the identity provider step (`idp`) wherever it stands: the vendor's connection is deleted, and the customer is back on our form for the provider's own password. A browser already made again on the signed in profile stays, on the provider's sign in page. No body.","security":[{"browserSession":[]}],"parameters":[{"$ref":"#/components/parameters/BrowserSessionId"}],"responses":{"202":{"description":"Back to the sign in.","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["awaiting_sign_in"]}}}}}},"401":{"description":"`browser_expired`: the token is wrong, expired, or for another session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"`browser_wrong_state`: no identity provider step is on the session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`browser_expired`: the session ran out of time.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/browser-sessions/{sid}:code":{"post":{"operationId":"codeBrowserSession","summary":"Send the code a provider's frame asked for","tags":["Cloud browser"],"description":"While the view says `handback: {reason: code, relay: true}`, the agent waits for a one time code the provider asks for in a frame of its own after the sign in (Squarespace's \"Verify to continue\"). The popup's own code screen sends it here; the agent types it into the provider's frame and presses its verify button. The code is kept nowhere: it goes to the waiting run and is forgotten, and it is in no log, trace or model prompt.","security":[{"browserSession":[]}],"parameters":[{"$ref":"#/components/parameters/BrowserSessionId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"additionalProperties":false,"properties":{"code":{"type":"string","description":"The code, 4 to 12 letters and digits (spaces and dashes are dropped)."}}}}}},"responses":{"204":{"description":"The agent has the code and types it now."},"400":{"description":"The body is not a small JSON object with a code of that shape. The code is never echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`browser_expired`: the token is wrong, expired, or for another session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"`browser_wrong_state`: no code is asked for now, or one is already on its way.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`browser_expired`: the session ran out of time.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/connect/oauth/callback":{"get":{"operationId":"oauthCallback","summary":"OAuth redirect target (public; authenticated by the signed state)","tags":["Connections"],"description":"$100","security":[],"parameters":[{"name":"code","in":"query","schema":{"type":"string"}},{"name":"state","in":"query","required":true,"schema":{"type":"string"}},{"name":"teamId","in":"query","schema":{"type":"string"},"description":"Vercel install flow: the team the integration was installed on."},{"name":"configurationId","in":"query","schema":{"type":"string"},"description":"Vercel install flow: the installation id."},{"name":"status","in":"query","schema":{"type":"string","enum":["approved","denied"]},"description":"Porkbun key handoff: the account holder's decision."},{"name":"requestToken","in":"query","schema":{"type":"string"},"description":"Porkbun key handoff: echoed by Porkbun; must match the request the server started."}],"responses":{"200":{"description":"HTML finish page (postMessages the outcome to the vetted return origin)"},"400":{"description":"Invalid, expired, or replayed state"}}}},"/connect/dc/callback":{"get":{"operationId":"dcCallback","summary":"Async one-click setup redirect target (public; authenticated by the signed state)","tags":["Connections"],"description":"**Rail A (async one-click setup) redirect target**, distinct from `/connect/oauth/callback` (Mode C), which discards its one-time token. It consumes the signed single-use `state` (rail-bound to async), exchanges the code for a **durable async grant** at the provider API base pinned into the `state` at start (never re-derived from fresh discovery), applies the template, and persists the **encrypted** grant so the connection can be re-applied / reverted server-side. Records are applied with `data.via = async`.","security":[],"parameters":[{"name":"code","in":"query","schema":{"type":"string"}},{"name":"state","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"HTML finish page (postMessages the outcome to the vetted return origin)"},"400":{"description":"Invalid, expired, replayed, or wrong-rail state"}}}},"/connect/dc/return/{state}":{"get":{"operationId":"dcSyncReturn","summary":"One-click sync return (public; authenticated by the signed state)","tags":["Connections"],"description":"Where the DNS provider sends the browser after the user approves or cancels a one-click sync apply. It is the `redirect_uri` the signed `apply_url` carries, **not** a bearer-authenticated endpoint. The signed single-use `state` rides in the path because some providers (Cloudflare) drop the separate `state` parameter. It records a provider-reported `error` on the connection, runs the propagation check at once, and returns the same HTML finish page as the OAuth callback, which postMessages `{ type: \"customdomain:oauth\", payload }` to the origin vetted at start. A clean return never marks the connection live by itself: only the records appearing in public DNS do.","security":[],"parameters":[{"name":"state","in":"path","required":true,"schema":{"type":"string"}},{"name":"error","in":"query","schema":{"type":"string"},"description":"OAuth 2.0 error code the provider reports (access_denied when the user cancels)."},{"name":"error_description","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"HTML finish page (postMessages the outcome to the vetted return origin)"},"400":{"description":"Invalid, expired, replayed, or wrong-rail state"},"503":{"description":"The return is not configured on this server"}}}},"/connect/dc/return":{"get":{"operationId":"dcSyncReturnQuery","summary":"One-click sync return with the state as a query parameter","tags":["Connections"],"description":"The same return as `/connect/dc/return/{state}`, for a provider that hands the signed state back as `?state=`.","security":[],"parameters":[{"name":"state","in":"query","required":true,"schema":{"type":"string"}},{"name":"error","in":"query","schema":{"type":"string"}},{"name":"error_description","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"HTML finish page (postMessages the outcome to the vetted return origin)"},"400":{"description":"Invalid, expired, replayed, or wrong-rail state"},"503":{"description":"The return is not configured on this server"}}}},"/connections/{id}/domainconnect:start":{"post":{"operationId":"startDomainConnect","summary":"Build the one-click apply URL (sync) or start the managed async rail","tags":["Connections"],"description":"$101","security":[{"widgetJWT":[]},{"apiKey":[]},{"agentToken":["domains:connect"]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"service_id":{"type":"string"},"service_ids":{"type":"array","items":{"type":"string"},"description":"Bundle of templates to authorize under one managed consent (async rail only). Wins over `service_id` when set."},"host":{"type":"string"},"vars":{"type":"object","additionalProperties":{"type":"string"},"description":"$102"},"managed":{"type":"boolean","description":"Opt into the managed (async) one-click rail."},"rail":{"type":"string","description":"Set to \"async\" to request the managed rail (same effect as managed:true)."},"return_origin":{"type":"string","description":"Vetted web origin the finish page may postMessage the outcome to; must be on the server allowlist. Used by the async callback, and by the sync return page on a plain sync start."}}}}}},"responses":{"200":{"description":"Sync rail returns `apply_url`; the managed async rail returns `consent_url` and `rail: \"async\"`.","content":{"application/json":{"schema":{"type":"object","properties":{"apply_url":{"type":"string","format":"uri","description":"Sync rail: provider-hosted apply URL."},"consent_url":{"type":"string","format":"uri","description":"Async rail: provider consent URL."},"service_id":{"type":"string"},"service_ids":{"type":"array","items":{"type":"string"},"description":"Async rail: the resolved template bundle."},"dc_provider":{"type":"string"},"rail":{"type":"string","description":"\"async\" on the managed rail; omitted on the sync rail."}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/ForbiddenSuspendedOrWrongEndUser"},"404":{"$ref":"#/components/responses/Error"},"422":{"description":"The target is a root (apex) domain that the selected template cannot serve. Branch on `code`: `apex_template_required` means the named template is `hostRequired` (or no apex-capable template is loaded): retry without `service_id`, or pass a `host` to set up a subdomain instead. `InvalidNameservers` means the domain has no usable NS delegation. `custom_routing` means the domain is routed to your own infrastructure (its `routing.mode` is `custom`) and the templates point domains at the CustomDomain™ edge: add the records manually or with a provider API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/route53-role:start":{"post":{"operationId":"startRoute53Role","summary":"Start connecting a Route 53 domain through a limited IAM role instead of an access key","tags":["Connections"],"description":"$103","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"hosted_zone_id":{"type":"string","description":"The Route 53 hosted zone that holds the domain, such as `Z23YXV4OVPL04A` (a `/hostedzone/` prefix is accepted). Optional: without it the AWS console lists the account's zones to choose from."}}}}}},"responses":{"200":{"description":"The quick-create link and the steps to show the customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Route53RoleStart"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/ForbiddenSuspendedOrWrongEndUser"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/route53-role:complete":{"post":{"operationId":"completeRoute53Role","summary":"Verify the customer's Route 53 access role and write the connection's records with it","tags":["Connections"],"description":"$104","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"role_arn":{"type":"string","description":"The stack's `RoleArn` output, such as `arn:aws:iam::123456789012:role/CustomDomainDNSAccess-0123456789abcdef0123456789abcdef`. Optional once a role has been verified for the connection."}}}}}},"responses":{"200":{"description":"The records were written and the connection is propagating.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Route53RoleComplete"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/ForbiddenOrWrongEndUser"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/sharing/connect":{"post":{"operationId":"createSharedFlow","summary":"Mint a share link that resumes a connect flow from a server-side prefill","tags":["Sharing"],"description":"$105","security":[{"widgetJWT":[]},{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"application_id":{"type":"string","description":"With an API key, the application the shared flow connects into (defaults to the key's own). A widget JWT may only omit it or send its own application id (403 otherwise)."},"domain":{"type":"string","description":"Single domain the teammate will connect."},"domains":{"type":"array","items":{"type":"string"},"description":"Several domains the teammate will connect."},"prefill":{"type":"object","additionalProperties":true,"description":"Arbitrary widget config to resume. Served back by `GET /share/{token}`, with its `domain` and `domains` keys replaced by the normalized targets from `domain` and `domains` above."},"recipient_email":{"type":"string","format":"email","maxLength":254,"description":"Optional. One plain address (no display name, no list) to email the link and the DNS records to, for example the person who runs the domain's DNS. The instructions cover `domain`, or the first of `domains`."},"note":{"type":"string","maxLength":280,"description":"Optional plain-text note quoted in the email (at most 280 characters; markup is shown as text, never interpreted). Ignored without `recipient_email`."}}}}}},"responses":{"201":{"description":"Share link minted (and, with recipient_email, the email attempted)","content":{"application/json":{"schema":{"type":"object","required":["link","job_id"],"properties":{"link":{"type":"string","format":"uri","description":"Absolute forwardable URL ending /share/."},"job_id":{"type":"string"},"emailed_to":{"type":"string","format":"email","description":"Present when the email was accepted for delivery; the normalized recipient address."},"email_error":{"type":"string","enum":["not_sent"],"description":"Present when recipient_email was given but the email could not be sent. The link is still valid."}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"description":"`forbidden` (the token is bound to a different domain, or its role cannot write connections) or `token_wrong_end_user` (a widget token that does not own the connection of a domain it asks to share: the connection names another end user, or names none while the token is not bound to that domain; no link is made).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"429":{"description":"Share-by-email cap reached (`rate_limited`); no link was minted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenAPISpec","summary":"This OpenAPI document","tags":["Meta"],"security":[],"description":"Returns this specification as JSON. Public and unauthenticated, cached for 5 minutes. It is the same document published at `apps/app/openapi-v1.yaml`, converted to JSON at build time and embedded in the binary, so the served copy can never drift from the source.","responses":{"200":{"description":"The OpenAPI 3.1 document.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/applications/{id}/nameserver-migrations":{"get":{"operationId":"listNameserverMigrations","summary":"One application's nameserver migrations and their analytics","tags":["Nameservers"],"description":"The application's nameserver migrations, newest first, with their analytics: counts per state, path and target, the median time to active, how many waited on DNSSEC and for how long, failures by code, rollbacks and drifts. Only this application's migrations; `since` narrows both the list and the analytics.","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"since","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Keep the migrations created at or after this time (RFC 3339)."}],"responses":{"200":{"description":"Migrations and analytics","content":{"application/json":{"schema":{"type":"object","required":["migrations","stats"],"properties":{"migrations":{"type":"array","items":{"$ref":"#/components/schemas/NameserverMigration"}},"stats":{"$ref":"#/components/schemas/NameserverMigrationStats"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/applications/{id}/client-secret:rotate":{"post":{"operationId":"rotateClientSecret","summary":"Rotate an application's widget client_secret (new secret returned once)","tags":["Applications"],"description":"Mints a fresh client_secret, stores only its hash, and returns the plaintext exactly once; it is never retrievable again. The old secret stops minting widget tokens (POST /tokens) immediately; already-issued widget JWTs run out their own short TTL. Admin-or-above (keys:manage): a member/viewer API key is rejected with 403.","security":[{"apiKey":[]},{"managementKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Rotated; the new client_secret is present only in this response","content":{"application/json":{"schema":{"type":"object","required":["application_id","client_secret"],"properties":{"application_id":{"type":"string"},"client_secret":{"type":"string","description":"sk_… (mints widget JWTs; shown once, stored hashed)"}}}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/BillingRequired"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/applications/{id}/edge-secret:rotate":{"post":{"operationId":"rotateEdgeSecret","summary":"Rotate an application's edge auth secret","tags":["Applications"],"description":"Mints a new `edge_auth_secret` for the application and invalidates the previous one immediately. There is no overlap window, so the edge must be reconfigured with the returned value before it can authenticate again. Requires `app:write` (member and above); a widget token cannot call it. The secret is returned once and is not retrievable afterwards.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Application id."}],"responses":{"200":{"description":"The new secret. Store it now; it is never shown again.","content":{"application/json":{"schema":{"type":"object","required":["application_id","edge_auth_secret"],"properties":{"application_id":{"type":"string"},"edge_auth_secret":{"type":"string","description":"The new shared secret. Shown exactly once."}}}}}},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/applications/{id}/email-sender":{"get":{"operationId":"getEmailSender","summary":"How an application's end user notices are sent","tags":["Applications"],"description":"Returns the application's email sender setting. With no setting saved the mode is `default` (the CustomDomain™ transactional sender). The SMTP password is write only: it is never returned, only `password_set`. Requires `app:read`.","security":[{"apiKey":[]},{"managementKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"The setting.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSender"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"put":{"operationId":"putEmailSender","summary":"Set how an application's end user notices are sent","tags":["Applications"],"description":"Replaces the setting. `mode` is `default` (the CustomDomain™ sender), `smtp` (the platform's own mail server, with the notice's From taken from `from_address` and `from_name`) or `none` (nothing is sent; use the `connection.records_outdated` webhook instead). With `smtp`, the host must be a public address, the port one of 25, 465, 587 or 2525, and TLS is always on: `implicit` on 465, `starttls` on the others. Plain text is not offered. The password is sealed at rest; leave `smtp_password` out to keep the stored one. A change of server, login or sender clears `verified_at`. A mail failure at send time falls back to the default sender for that message and is recorded in `last_error`. Requires `app:write`.","security":[{"apiKey":[]},{"managementKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSenderInput"}}}},"responses":{"200":{"description":"Saved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSender"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/applications/{id}/email-sender:test":{"post":{"operationId":"testEmailSender","summary":"Send one test message through an application's mail server","tags":["Applications"],"description":"Sends a short test message to `to` through the saved SMTP server (`mode` must be `smtp`). On success `verified_at` is recorded; on failure `last_error` is recorded (with no secret in it) and the response is 502. Limited to 5 per hour per application. Requires `app:write`.","security":[{"apiKey":[]},{"managementKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to"],"properties":{"to":{"type":"string","description":"A plain email address."}}}}}},"responses":{"200":{"description":"Sent.","content":{"application/json":{"schema":{"type":"object","required":["ok","verified_at"],"properties":{"ok":{"type":"boolean"},"verified_at":{"type":"string","format":"date-time"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/billing/setup":{"post":{"operationId":"startCardSetup","summary":"Start a Stripe Checkout session to save a payment method","tags":["Billing"],"description":"$106","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"return_url":{"type":"string","description":"Where Checkout returns the user (embedded and elements flows)."},"success_url":{"type":"string","description":"Hosted redirect flow; requires cancel_url too."},"cancel_url":{"type":"string","description":"Hosted redirect flow; requires success_url too."},"ui_mode":{"type":"string","enum":["embedded","elements"],"description":"How the session is shown. Leave it out (or send null or an empty string) for Stripe Embedded Checkout when `return_url` is set and the hosted redirect when only `success_url` and `cancel_url` are. `elements` requires `return_url`. Never send `hosted`: it is only an answer."}}}}}},"responses":{"200":{"description":"The Checkout session. Embedded and elements flows read `client_secret`; redirect flows read `url`.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","description":"Hosted Checkout URL (redirect flow)."},"client_secret":{"type":"string","description":"Client secret to mount the embedded or elements checkout with."},"ui_mode":{"type":"string","enum":["embedded","elements","hosted"],"description":"How the session was really created. An `elements` request answers `embedded` when Stripe could not create an Elements session."}}}}}},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/analytics/connect":{"get":{"operationId":"getConnectAnalytics","summary":"Connect funnel and connection outcomes","tags":["Analytics"],"description":"The widget funnel (sessions, how many entered a domain, were offered a one-click or sign-in rail, were shown records to copy, succeeded, where the rest stopped, per provider and root versus subdomain) and connection outcomes (live rate, time to live, per provider and method, why the rest are stuck), plus a daily series. `audience` counts the widget sessions by device type, country, browser, operating system and embed (no address, no city, no session listed), `install` whether the widget was seen in the builder's own product or only in the console's tests (per application), and `secure_sign_in` the cloud browser sessions started in the window: the funnel per provider, the failures by reason, and the same with and without a vendor proxy. Both are scoped like the rest, to the key's workspace and `app_id` when given. API key; any member role.","security":[{"apiKey":[]}],"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":180,"default":30}},{"name":"app_id","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectAnalytics"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/analytics/secure-sign-in":{"get":{"operationId":"getSecureSignInFlow","summary":"Secure sign-in funnel, time per stage and where sessions stop","tags":["Analytics"],"description":"$107","security":[{"apiKey":[]}],"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":180,"default":30}},{"name":"app_id","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The flow","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecureSignInFlow"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/analytics/secure-sign-in/sessions":{"get":{"operationId":"listSecureSignInSessions","summary":"The newest secure sign-in sessions","tags":["Analytics"],"description":"The newest sessions in the window, one row each: provider, when it started, how it ended (`done`, `done_by_hand`, `running`, `stopped`), the furthest stage it reached, the plain reason it stopped, the last step logged before the end and the seconds from start to end. `connection_id` narrows to one domain's sessions, `provider` to one DNS provider. Pick a row's `id` for its timeline. API key; any member role.","security":[{"apiKey":[]}],"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":180,"default":30}},{"name":"app_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"connection_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"provider","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"The sessions","content":{"application/json":{"schema":{"type":"object","required":["sessions"],"properties":{"sessions":{"type":"array","items":{"$ref":"#/components/schemas/SecureSignInSession"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/analytics/secure-sign-in/sessions/{sid}":{"get":{"operationId":"getSecureSignInTimeline","summary":"One secure sign-in session's steps","tags":["Analytics"],"description":"The session's row plus its steps in order, each with the seconds since the session started, so one slow or failed run can be read. A step is a word from a fixed list (a state the session moved to, or a step the sign-in window reported), with the failure it ended in, if any, and one short detail word. It never holds a code, a password, a domain or anything typed. 404 for a session of another workspace. API key; any member role.","security":[{"apiKey":[]}],"parameters":[{"name":"sid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The timeline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecureSignInTimeline"}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/traffic":{"get":{"operationId":"getTrafficSummary","summary":"Edge traffic for the workspace or one application, with its busiest domains","tags":["Analytics"],"description":"Requests the CustomDomain™ edge served for the tenant's domains, by status class, and the bytes it relayed to visitors, as a series (one point per hour for `24h` and `7d`, per UTC day for `30d` and `90d`, every bucket present) with totals and the busiest domains. Only traffic that passes through the edge is counted: a domain whose records point at the integrator's own servers (connected for DNS only) never appears. Counts arrive from the edge once a minute. Hourly figures are kept 14 days, daily figures 400 days. API key; any member role; `app_id` narrows to one application of the key's tenant (another tenant's application is a 404).","security":[{"apiKey":[]}],"parameters":[{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["24h","7d","30d","90d"],"default":"7d"}},{"name":"app_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"How many of the busiest domains to return.","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}}],"responses":{"200":{"description":"Traffic summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrafficSummary"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/traffic":{"get":{"operationId":"getConnectionTraffic","summary":"Edge traffic for one domain","tags":["Analytics"],"description":"$108","security":[{"apiKey":[]},{"widgetJWT":[]},{"agentToken":["domains:read"]}],"parameters":[{"$ref":"#/components/parameters/Id"},{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["24h","7d","30d","90d"],"default":"7d"}}],"responses":{"200":{"description":"Domain traffic","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionTraffic"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/share/{token}":{"servers":[{"url":"https://api.customdomain.ai","description":"Hosted control-plane (share links are not under /v1)"},{"url":"http://localhost:8080","description":"Local control-plane"}],"get":{"operationId":"getSharedFlow","summary":"Read a share link's server-side prefill (token is the bearer credential)","tags":["Sharing"],"description":"$109","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Shared flow prefill","content":{"application/json":{"schema":{"type":"object","required":["token","application_id","job_id","prefill"],"properties":{"token":{"type":"string"},"application_id":{"type":"string"},"job_id":{"type":"string"},"prefill":{"type":"object","additionalProperties":true}}}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/providers":{"get":{"operationId":"listProviders","summary":"List the DNS providers the Connect engine can detect and automate","tags":["Providers"],"security":[],"responses":{"200":{"description":"Provider capability catalog","content":{"application/json":{"schema":{"type":"object","required":["providers","count"],"properties":{"providers":{"type":"array","items":{"$ref":"#/components/schemas/ProviderInfo"}},"count":{"type":"integer"}}}}}}}}},"/providers/census":{"get":{"operationId":"providerCensus","summary":"Full parity census (every target provider routed to its working mode)","tags":["Providers"],"security":[],"responses":{"200":{"description":"Census (each provider routed to dc / oauth / api / manual)","content":{"application/json":{"schema":{"type":"object","required":["providers","count"],"properties":{"providers":{"type":"array","items":{"type":"object"}},"count":{"type":"integer"}}}}}}}}},"/templates":{"get":{"operationId":"listTemplates","summary":"List one-click setup service templates","tags":["Templates"],"security":[],"responses":{"200":{"description":"Template list"},"503":{"$ref":"#/components/responses/Error"}}}},"/templates/{serviceId}":{"get":{"operationId":"getTemplate","summary":"Get one setup template","tags":["Templates"],"security":[],"parameters":[{"name":"serviceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Template"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/templates/{serviceId}/apply-url":{"post":{"operationId":"buildTemplateApplyUrl","summary":"Build the one-click apply URL for a domain","tags":["Templates"],"security":[],"parameters":[{"name":"serviceId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain","provider_base"],"properties":{"domain":{"type":"string"},"host":{"type":"string"},"provider_base":{"type":"string"},"vars":{"type":"object","additionalProperties":{"type":"string"},"description":"The template's caller-supplied variables, the same set `POST /connections/{id}/domainconnect:start` takes. `edgeIp` and `edgeIp6` are set by the server; naming one, or a variable the template does not take, answers `400 invalid_request`. An unknown template answers `404`."}}}}}},"responses":{"200":{"description":"apply_url","content":{"application/json":{"schema":{"type":"object","properties":{"apply_url":{"type":"string","format":"uri"}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/registrar/search":{"get":{"operationId":"searchDomains","summary":"Search domain availability and pricing","tags":["Registrar"],"description":"Availability and retail prices for the typed name. With `suggest=1` it also returns the same name on other TLDs and close variants, each result carrying a `kind` (`exact`, `tld` or `variant`). A widget token of either scope, a tenant API key of any role, or a delegated agent token with `domains:read` may search.","security":[{"widgetJWT":[]},{"apiKey":[]},{"agentToken":["domains:read"]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"suggest","in":"query","required":false,"description":"Send `1` for the shop style search: the typed name, the same name on other TLDs and close variants, each with a `kind`.","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"Results"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/registrar/quote":{"post":{"operationId":"quoteDomain","summary":"Cheapest real-time price for a domain","tags":["Registrar"],"description":"The registrar's cheapest real time price for a domain, with the retail markup applied. A widget token of either scope, a tenant API key of any role, or a delegated agent token with `domains:read` may ask.","security":[{"widgetJWT":[]},{"apiKey":[]},{"agentToken":["domains:read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string"}}}}}},"responses":{"200":{"description":"Price"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/registrar/purchase":{"post":{"operationId":"purchaseDomain","summary":"Register a domain (fail-closed; requires Idempotency-Key)","tags":["Registrar"],"description":"Off on the hosted service. This route registers a domain without taking a payment, so it needs both `SELL_PURCHASE_ENABLED` and its own switch `SELL_DIRECT_PURCHASE_ENABLED`; buy through checkout instead. A required `Idempotency-Key` header dedupes retries so a registration is never charged twice.\n\nA delegated agent token needs `domains:purchase`; the grant's monthly spend cap is charged first, and a purchase that would pass it answers `409`. A tenant API key is refused with `401`. A workspace that billing refuses answers `402`.","security":[{"widgetJWT":[]},{"agentToken":["domains:purchase"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain","buyer"],"properties":{"domain":{"type":"string"},"buyer":{"type":"object","required":["email"],"properties":{"name":{"type":"string"},"email":{"type":"string"},"country":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Order (idempotent replay)"},"201":{"description":"Order"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/BillingRequired"},"403":{"$ref":"#/components/responses/ForbiddenOrSuspended"},"503":{"$ref":"#/components/responses/Error"}}}},"/monitor:check":{"post":{"operationId":"checkRecords","summary":"Check declared baseline records against live public DNS","tags":["Monitor"],"description":"Resolves each baseline record and reports whether it is still present. This is what the SDK's `checkRecords` rides on. Read-only; performs no writes.","security":[{"widgetJWT":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain","baseline"],"properties":{"domain":{"type":"string"},"baseline":{"type":"array","items":{"type":"object","properties":{"subdomain":{"type":"string"},"type":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}}}}}}}}},"responses":{"200":{"description":"Drift report"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/monitor/domains":{"get":{"operationId":"listMonitoredDomains","summary":"Every domain of the workspace with its last drift check","tags":["Monitor"],"description":"The monitoring state of the domains in the API key's workspace (or one application with `app_id`), the ones needing attention first, a page at a time, with counts over every domain. Pass the previous page's `next_cursor` as `cursor` for the next page; there is no `next_cursor` on the last one. The per domain detail (watched records, repair route, history) is on `GET /connections/{id}/monitor`.","security":[{"apiKey":[]}],"parameters":[{"name":"app_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":200},"description":"Domains per page; a larger value is read as 1000."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"The previous page's `next_cursor`."}],"responses":{"200":{"description":"One page of domains, and a summary of all of them","content":{"application/json":{"schema":{"type":"object","required":["domains","summary","every","auto_repair"],"properties":{"every":{"type":"string"},"auto_repair":{"type":"boolean","description":"Whether this deployment puts missing records back automatically (`MONITOR_AUTO_REPAIR`)."},"next_cursor":{"type":"string","description":"Present when more domains follow; pass it as `cursor`."},"summary":{"type":"object","properties":{"domains":{"type":"integer"},"watched":{"type":"integer"},"ok":{"type":"integer"},"drift":{"type":"integer"},"needs_action":{"type":"integer"},"inconclusive":{"type":"integer"},"unconfirmed":{"type":"integer"},"not_checked":{"type":"integer"}}},"domains":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/MonitorView"},{"type":"object","properties":{"application_id":{"type":"string"},"status":{"type":"string"}}}]}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}}}},"/webhooks":{"post":{"operationId":"createWebhook","summary":"Register a webhook endpoint (secret returned once)","tags":["Webhooks"],"description":"Registers an HTTPS receiver under the calling application. The `secret` (`whsec_…`) is returned ONCE. Store it to verify signatures. An empty `events` array subscribes to all events; `\"*\"` also matches all.","security":[{"widgetJWT":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","description":"$10a","items":{"type":"string","enum":["*","domain.record_missing","domain.record_restored","domain.purchased","purchase.error","purchase.confirmation.expired","secure_status","power_status","connection.created","connection.applied","connection.live","connection.failed","connection.records.updated","connection.reapply.failed","connection.records_outdated","connection.disconnected","certificate.issued","certificate.renewed","certificate.failed","certificate.expiring","credential.created","credential.expiring","credential.failed","credential.removed","nameservers.started","nameservers.dnssec_cleared","nameservers.changed","nameservers.active","nameservers.failed","nameservers.rolled_back","nameservers.drifted"]}}}}}}},"responses":{"201":{"description":"Created (secret returned once)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"listWebhooks","summary":"List webhook endpoints","tags":["Webhooks"],"description":"With an API key: endpoints across all the tenant's live apps (a test mode application's endpoints are left out unless `?app_id=` names it). With a test mode API key: that application's endpoints. With a widget JWT: the calling app's endpoints. Secrets are omitted.","security":[{"apiKey":[]},{"widgetJWT":[]}],"parameters":[{"name":"app_id","in":"query","required":false,"schema":{"type":"string"},"description":"Narrow to one application, which is how a live key reaches a test mode application's endpoints."}],"responses":{"200":{"description":"Endpoints","content":{"application/json":{"schema":{"type":"object","required":["webhooks"],"properties":{"webhooks":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}}},"401":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/webhooks/{id}":{"delete":{"operationId":"deleteWebhook","summary":"Delete a webhook endpoint","tags":["Webhooks"],"security":[{"widgetJWT":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"204":{"description":"Deleted"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/webhook-deliveries":{"get":{"operationId":"listWebhookDeliveries","summary":"Recent webhook delivery attempts for the caller's tenant","tags":["Webhooks"],"description":"API key: all the tenant's apps. Widget JWT: the calling app. `?app_id=` narrows to one application; `?type=` filters by event type.","security":[{"apiKey":[]},{"widgetJWT":[]}],"parameters":[{"name":"app_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"type","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deliveries","content":{"application/json":{"schema":{"type":"object","required":["deliveries","count"],"properties":{"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"count":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/plans":{"get":{"operationId":"listPlans","summary":"Public plan catalog (plus billing {configured, mode})","tags":["Billing"],"description":"The public plan catalog: `starter` ($10 a month, 10 new domains in any 12 months, the default for a new workspace, 14 day trial), `startup`, `growth`, and the contact-sales `premium` and `enterprise`. The retired `free` plan is not listed; a workspace created before it was retired keeps it until it subscribes. The figures above are the defaults: an operator can change a plan's `price_cents`, `domains_per_year` (and so `domains_per_month` and `quota`), `trial_days` and `hard_cap` without a release, so read them from this response rather than hard coding them. `billing.trial_days` is the default plan's trial.","security":[],"responses":{"200":{"description":"Plans","content":{"application/json":{"schema":{"type":"object","properties":{"plans":{"type":"array","items":{"$ref":"#/components/schemas/Plan"}},"billing":{"type":"object","properties":{"configured":{"type":"boolean","description":"Whether a Stripe key is configured."},"mode":{"type":"string","enum":["test","live",""]},"trial_days":{"type":"integer","description":"The trial a new workspace's first subscription to the default plan starts with (0: no trial)."}}}}}}}}}}},"/billing/usage":{"get":{"operationId":"getUsage","summary":"Metered domain usage, plan, and quota for the caller's tenant","tags":["Billing"],"description":"The tenant is derived from the authenticated credential, never a query parameter. `?period=` defaults to the current UTC calendar month.","security":[{"apiKey":[]},{"widgetJWT":[]}],"parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string","examples":["2026-07"]}}],"responses":{"200":{"description":"Usage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/billing/checkout":{"post":{"operationId":"createCheckout","summary":"Start a Stripe Checkout session for a self-serve plan","tags":["Billing"],"description":"$10b","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["plan"],"properties":{"plan":{"$ref":"#/components/schemas/PlanId"},"success_url":{"type":"string","format":"uri"},"cancel_url":{"type":"string","format":"uri"},"return_url":{"type":"string","format":"uri","description":"Selects embedded Checkout, or the elements checkout with ui_mode elements."},"ui_mode":{"type":"string","enum":["embedded","elements"],"description":"How the session is shown. Leave it out (or send null or an empty string) for Stripe Embedded Checkout when `return_url` is set and the hosted redirect when only `success_url` and `cancel_url` are. `elements` requires `return_url`. Never send `hosted`: it is only an answer."},"promotion_code":{"type":"string","maxLength":64,"description":"A promotion code as a customer types it (never a Stripe `promo_` id). Taken only when it is one of CustomDomain's own, and then the session's one discount. Not found, not CustomDomain's, or no longer active is a `404`."}}}}}},"responses":{"200":{"description":"Checkout session","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","description":"Hosted Checkout URL (redirect flow)."},"client_secret":{"type":"string","description":"Client secret to mount the embedded or elements checkout with."},"ui_mode":{"type":"string","enum":["embedded","elements","hosted"],"description":"How the session was really created. An `elements` request answers `embedded` when Stripe could not create an Elements session."},"trial_days":{"type":"integer","description":"Trial length, when the checkout starts one by days."},"trial_end":{"type":["string","null"],"format":"date-time","description":"When the trial ends, when it ends at a fixed time (the grace end)."},"first_charge_at":{"type":"string","format":"date-time","description":"When the card is first charged, when there is a trial."}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"description":"The `promotion_code` does not exist, is no longer active, or is not one of CustomDomain's own.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/billing/portal":{"post":{"operationId":"createPortalSession","summary":"Open a Stripe Billing Portal session","tags":["Billing"],"description":"Opens the Stripe Billing Portal (invoices, the card, cancellation) for the caller's workspace. Requires `billing:manage` (owners and admins) and a Stripe customer (a completed checkout). `flow` deep-links into one task: `payment_method_update` (the \"update your card\" link of a payment failure email) or `subscription_cancel`.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["return_url"],"properties":{"return_url":{"type":"string","format":"uri"},"flow":{"type":"string","enum":["payment_method_update","subscription_cancel"]}}}}}},"responses":{"200":{"description":"Portal session","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/billing/notice":{"get":{"operationId":"getBillingNotice","summary":"Whether billing needs attention (every member)","tags":["Billing"],"description":"What the console needs on every page to decide on a billing banner or the setup flow. Any member of the workspace may read it with their own tenant API key. Members and viewers get only `role`, `can_manage`, `configured`, `attention` and `restricted`: never the plan, dates or amounts. Owners and admins also get the billing state, and `first_domain_free` with `free_domains` (how many domains it may connect before a card) while a new workspace is on the first domain free rule.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Billing notice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingNotice"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}}},"/billing/standing":{"get":{"operationId":"getBillingStanding","summary":"Whether the workspace may connect new domains","tags":["Billing"],"description":"The lean read the MCP server's `check-billing-status` tool uses: whether a new connection is refused right now, and if so the same `code`, `title` and `details` the refusal carries (`billing_required`), plus the plan and its usage over the quota window (12 months on Starter, else this month). It has no dates, amounts, invoices or card; owners and admins read those from `GET /billing/status`. Any workspace credential may read it: a tenant API key of any role, a delegated agent token with `domains:read`, or a widget token minted with scope `app`. A `connect`-scoped widget token (an end user's) is refused with `403`.","security":[{"apiKey":[]},{"widgetJWT":[]},{"agentToken":["domains:read"]}],"responses":{"200":{"description":"The workspace's standing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingStanding"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}}},"/billing/status":{"get":{"operationId":"getBillingStatus","summary":"The workspace's subscription (owners and admins)","tags":["Billing"],"description":"The billing page: plan, state, trial or grace countdown, the next charge, the card on file, what a checkout started now would give, and usage over the quota window (12 months on Starter, else this month). Requires `billing:manage` (owners and admins); members and viewers get `403`.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Billing status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingStatus"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/billing/invoices":{"get":{"operationId":"listBillingInvoices","summary":"The workspace's recent invoices (owners and admins)","tags":["Billing"],"description":"Read from Stripe, newest first. Requires `billing:manage`.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Invoices","content":{"application/json":{"schema":{"type":"object","properties":{"invoices":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/billing/grace:start":{"post":{"operationId":"startBillingGrace","summary":"Start a legacy Free workspace's grace period (owners and admins)","tags":["Billing"],"description":"Called by the console when an owner or admin opens it: a workspace still on the retired Free plan gets its 14 day grace period from now (and its owners and admins an email). Idempotent, and a no-op in any other state. A Free workspace that never signs in gets the same grace at its first connection attempt. Requires `billing:manage`.","security":[{"apiKey":[]}],"responses":{"200":{"description":"The grace state","content":{"application/json":{"schema":{"type":"object","properties":{"started":{"type":"boolean","description":"Whether this call started the grace."},"state":{"$ref":"#/components/schemas/BillingState"},"grace_ends_at":{"type":["string","null"],"format":"date-time"},"days_left":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/billing/checkout:confirm":{"post":{"operationId":"confirmBillingCheckout","summary":"Record a completed plan checkout now (owners and admins)","tags":["Billing"],"description":"Called when Stripe returns the browser from a completed Checkout, so the subscription is recorded at once instead of when Stripe's `checkout.session.completed` event arrives. The session is read from Stripe, never trusted from the caller: it must belong to the caller's workspace (another workspace's session is a `404`) and be complete and paid (a trial's \"no payment required\" counts); otherwise `confirmed` is false and nothing changes. A paid second checkout for a workspace whose subscription still bills is held for review: `confirmed` is false, nothing changes, and the billing view shows the subscription that still bills. Idempotent with the webhook. Requires `billing:manage`.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["session_id"],"properties":{"session_id":{"type":"string","examples":["cs_test_a1B2c3"]}}}}}},"responses":{"200":{"description":"Whether the checkout was recorded, and the billing status after","content":{"application/json":{"schema":{"type":"object","properties":{"confirmed":{"type":"boolean"},"session_status":{"type":"string","examples":["complete","open"]},"payment_status":{"type":"string","examples":["paid","no_payment_required","unpaid"]},"billing":{"$ref":"#/components/schemas/BillingStatus"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/billing/change-plan":{"post":{"operationId":"changeBillingPlan","summary":"Move a running subscription to another self-serve plan","tags":["Billing"],"description":"Swaps the price of the workspace's running Stripe subscription (Stripe prorates the difference). Self-serve plans only; a workspace without a running subscription gets `409` and subscribes through `/billing/checkout`. Requires `billing:manage`.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["plan"],"properties":{"plan":{"$ref":"#/components/schemas/PlanId"}}}}}},"responses":{"200":{"description":"The new billing status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingStatus"}}}},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/billing/promotion-code":{"post":{"operationId":"applyBillingPromotionCode","summary":"Apply a promotion code to the running subscription","tags":["Billing"],"description":"Applies a promotion code, as a customer types it, to the workspace's running subscription (a new subscription takes a code as `promotion_code` on `POST /billing/checkout`). A code is accepted only when it belongs to this deployment, because a Stripe account can be shared with other products: it was created through the operator console, or its coupon is limited to this deployment's Stripe products. An unknown, inactive or foreign code is a `404`. Requires `billing:manage`.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}}}},"responses":{"200":{"description":"The new billing status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingStatus"}}}},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/rbac":{"get":{"operationId":"getRbac","summary":"Role / permission matrix (static reference)","tags":["Enterprise"],"security":[],"responses":{"200":{"description":"Matrix"}}}},"/audit":{"get":{"operationId":"getAudit","summary":"Audit log (tenant-scoped for tenant credentials; full log for the management key)","tags":["Enterprise"],"security":[{"managementKey":[]},{"apiKey":[]},{"widgetJWT":[]}],"responses":{"200":{"description":"Events"},"401":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"recordAuditEvent","summary":"Record an audit event for a change made in the console","tags":["Enterprise"],"description":"$10c","security":[{"apiKey":[]},{"provisionSecret":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["whitelabel.configured","api_key.default_revealed","user.disabled","user.enabled","user.sessions_revoked","user.verification_resent","user.password_reset_link_issued","workspace.features_set"],"description":"The console-recordable verb. With an API key only `whitelabel.configured` and `api_key.default_revealed`; with the provisioning secret only the others. Any other value is refused with `400`."},"tenant_id":{"type":"string","description":"Provisioning secret only, and required with it: the workspace the event is recorded on. An unknown one is a `404`."},"target":{"type":"string","description":"What the event is about. Defaults to the caller's own organization when empty."},"before":{"type":"object","additionalProperties":true,"description":"A small summary of the state before the change; at most 24 keys."},"after":{"type":"object","additionalProperties":true,"description":"A small summary of the state after the change; at most 24 keys."}}}}}},"responses":{"200":{"description":"Recorded","content":{"application/json":{"schema":{"type":"object","required":["recorded","action"],"properties":{"recorded":{"type":"boolean"},"action":{"type":"string","description":"The verb that was recorded."}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/ssl":{"get":{"operationId":"getConnectionCertificate","summary":"Read the mirrored TLS certificate status for a connection's domain","tags":["Secure"],"description":"The control-plane's read-mirror of the edge certificate store for this connection's domain. `404` when no certificate is tracked yet.\n\nA widget token must be the connection's end user: a connection that names another end user than the token's `end_user_ref`, or names one while the token names none, answers `403` `token_wrong_end_user` before anything is read or changed, and a connection that names none is any token's. An API key, an app-scoped token and a delegated agent token are not limited by it.","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Certificate status","content":{"application/json":{"schema":{"type":"object","properties":{"certificate":{"$ref":"#/components/schemas/Certificate"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/ForbiddenOrWrongEndUser"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"deprovisionConnectionCertificate","summary":"Deprovision a connection's certificate (drop the mirror, stop managing)","tags":["Secure"],"description":"Drops the mirror row and clears `secure_root_domain`; the edge stops managing the certificate on its next reconcile. A row another application tracks for the same domain is left in place.","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"204":{"description":"Deprovisioned"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/ssl:eligibility":{"get":{"operationId":"getConnectionCertificateEligibility","summary":"Whether a certificate can be issued for this connection yet","tags":["Secure"],"description":"Advisory: a certificate is only issuable once the domain points at the edge (connection `live` or `propagating`). The widget/console uses this to gate the provision button.\n\nA widget token must be the connection's end user: a connection that names another end user than the token's `end_user_ref`, or names one while the token names none, answers `403` `token_wrong_end_user` before anything is read or changed, and a connection that names none is any token's. An API key, an app-scoped token and a delegated agent token are not limited by it.","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Eligibility","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Eligibility"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/ForbiddenOrWrongEndUser"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/ssl:provision":{"post":{"operationId":"provisionConnectionCertificate","summary":"Record intent to issue an edge-managed certificate","tags":["Secure"],"description":"Creates/updates the mirror row as `pending` + managed. The edge performs the actual ACME issuance on first handshake and reports back. Optionally sets `secure_root_domain` so the edge also secures the registrable apex. A domain has one certificate row. Returns 409 when another application tracks that row, unless this connection is the one the edge serves and the row's application serves nothing for the domain, in which case this connection takes the row over.","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"secure_root_domain":{"type":"boolean","description":"also secure the registrable apex."}}}}}},"responses":{"202":{"description":"Provisioning requested","content":{"application/json":{"schema":{"type":"object","properties":{"certificate":{"$ref":"#/components/schemas/Certificate"}}}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/ssl:renew":{"post":{"operationId":"renewConnectionCertificate","summary":"Mark a connection's certificate for renewal","tags":["Secure"],"description":"Records the operator-requested renew and surfaces `renewing`. The edge's autocert manager performs the actual renewal ahead of expiry.","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"202":{"description":"Renewal requested","content":{"application/json":{"schema":{"type":"object","properties":{"certificate":{"$ref":"#/components/schemas/Certificate"}}}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/ssl:import":{"post":{"operationId":"importConnectionCertificate","summary":"Record an operator-supplied (externally obtained) certificate's metadata","tags":["Secure"],"description":"Mirrors the status + validity window of an external certificate for display (`managed=false`, so the edge does not ACME-renew it). Private key material is an edge concern and is not handled here. Returns 409 when another application tracks the domain's certificate row, unless this connection is the one the edge serves and the row's application serves nothing for the domain, in which case this connection takes the row over.","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"issuer":{"type":"string"},"not_before":{"type":"string","format":"date-time","description":"RFC3339."},"not_after":{"type":"string","format":"date-time","description":"RFC3339."}}}}}},"responses":{"200":{"description":"Imported","content":{"application/json":{"schema":{"type":"object","properties":{"certificate":{"$ref":"#/components/schemas/Certificate"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/ssl":{"get":{"operationId":"listCertificates","summary":"List the certificates tracked for the caller's application","tags":["Secure"],"security":[{"widgetJWT":[]},{"apiKey":[]}],"responses":{"200":{"description":"Certificates","content":{"application/json":{"schema":{"type":"object","properties":{"certificates":{"type":"array","items":{"$ref":"#/components/schemas/Certificate"}}}}}}},"401":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/power":{"get":{"operationId":"getConnectionPower","summary":"Read a connection's Power (edge reverse-proxy) configuration","tags":["Power"],"description":"A widget token must be the connection's end user: a connection that names another end user than the token's `end_user_ref`, or names one while the token names none, answers `403` `token_wrong_end_user` before anything is read or changed, and a connection that names none is any token's. An API key, an app-scoped token and a delegated agent token are not limited by it.","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Power configuration","content":{"application/json":{"schema":{"type":"object","properties":{"power":{"$ref":"#/components/schemas/PowerConfig"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/ForbiddenOrWrongEndUser"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"enableConnectionPower","summary":"Enable Power (register the origin + redirect/root-path config)","tags":["Power"],"description":"Registers the origin the edge reverse-proxies to (SSRF-validated) plus the redirect / root-path config the ask answer carries. `application_url` is required to enable.","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PowerConfigInput"}}}},"responses":{"201":{"description":"Power enabled","content":{"application/json":{"schema":{"type":"object","properties":{"power":{"$ref":"#/components/schemas/PowerConfig"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"`conflict`: the call changes a redirect or the root path access of a domain that is being removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`redirect_target_not_allowed` or `redirect_loop` for `redirect_to` or `www_redirect`: the same checks as `PATCH /connections/{id}`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/RedirectsBusy"}}},"delete":{"operationId":"disableConnectionPower","summary":"Remove Power (drop the origin, clear config, tear down the cert)","tags":["Power"],"security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"description":"Clears the forward and the root path access, drops the origin and tears down the certificate. Clearing a forward is checked like any redirect change: on a domain whose `www` redirect is on, the visit that went to the forward now goes to the `www` name, and when that would come back (`www` forwards to the root) the call is refused with `422` `redirect_loop` and nothing is changed, the origin included. The `www` redirect itself is not cleared here (`PATCH /connections/{id}` turns it off).","responses":{"204":{"description":"Power removed"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"`conflict`: the domain's forward or root path access is set and the domain is being removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`redirect_loop`: taking the forward off would send a visit round a circle through the `www` redirect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/RedirectsBusy"}}}},"/applications/{id}/power:default":{"get":{"operationId":"getApplicationDefaultOrigin","summary":"The application-wide default origin","tags":["Power"],"description":"The origin the edge proxies to for any of this application's connections that have no origin of their own. Resolution order is: the connection's own origin, then this default, then none (the edge answers 421).\n\nThis exists because a per-connection origin is the wrong grain for the common case: one application serving thousands of customer domains, all proxying to the same place and dispatching on `X-Forwarded-Host`.","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"The current default","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationDefaultOrigin"}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}},"put":{"operationId":"setApplicationDefaultOrigin","summary":"Set or clear the application-wide default origin","tags":["Power"],"description":"Send `default_origin: \"\"` to clear it. The value is validated by the same guard a per-connection origin gets, and the edge re-validates the RESOLVED address at dial time: a hostname that passes here and is later repointed at a private address is refused when the edge connects.","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["default_origin"],"properties":{"default_origin":{"type":"string","description":"Absolute http(s) URL, or \"\" to clear.","example":"https://app.yourcompany.com"}}}}}},"responses":{"200":{"description":"The stored default","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationDefaultOrigin"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/applications/{id}/connect-target":{"get":{"operationId":"getConnectTarget","summary":"Where this application's customer domains point","tags":["Applications"],"description":"`mode: edge` (the default) points customer domains at the platform edge, which proxies their traffic to your origin (Power, Growth plan and up, once a default origin is set; without one the edge answers 421). `mode: custom` points them at your own infrastructure: subdomains get a CNAME to `cname_target`; a root domain gets an ALIAS, ANAME or flattened CNAME to it on providers that have one, and A records to `apex_ipv4` elsewhere. `edge` echoes what edge mode points at, so a console can show both options.","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Connection target","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectTargetView"}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"put":{"operationId":"setConnectTarget","summary":"Point this application's customer domains at your own infrastructure","tags":["Applications"],"description":"$10d","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cname_target"],"properties":{"cname_target":{"type":"string","description":"Hostname, or \"\" for the edge."},"apex_ipv4":{"type":"array","maxItems":4,"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Connection target","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectTargetView"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/power:eligibility":{"get":{"operationId":"getConnectionPowerEligibility","summary":"Whether Power can be enabled for this connection yet","tags":["Power"],"description":"Power needs the domain pointing at the edge (connection `live` or `propagating`) so the reverse proxy receives its traffic.\n\nA widget token must be the connection's end user: a connection that names another end user than the token's `end_user_ref`, or names one while the token names none, answers `403` `token_wrong_end_user` before anything is read or changed, and a connection that names none is any token's. An API key, an app-scoped token and a delegated agent token are not limited by it.","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Eligibility","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Eligibility"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/ForbiddenOrWrongEndUser"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/connections/{id}/power:repower":{"post":{"operationId":"repowerConnection","summary":"Update an existing Power configuration","tags":["Power"],"description":"Update the origin and/or config. Omitting `application_url` keeps the current origin (unlike enable, which requires it).","security":[{"widgetJWT":[]},{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PowerConfigInput"}}}},"responses":{"200":{"description":"Power updated","content":{"application/json":{"schema":{"type":"object","properties":{"power":{"$ref":"#/components/schemas/PowerConfig"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"`conflict`: the call changes a redirect or the root path access of a domain that is being removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`redirect_target_not_allowed` or `redirect_loop` for `redirect_to` or `www_redirect`: the same checks as `PATCH /connections/{id}`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/RedirectsBusy"}}}},"/power":{"get":{"operationId":"listPoweredConnections","summary":"List the caller app's powered connections","tags":["Power"],"security":[{"widgetJWT":[]},{"apiKey":[]}],"responses":{"200":{"description":"Powered connections","content":{"application/json":{"schema":{"type":"object","properties":{"power":{"type":"array","items":{"$ref":"#/components/schemas/PowerConfig"}}}}}}},"401":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/connections:bulk":{"post":{"operationId":"bulkCreateConnections","summary":"Create connections for a set of domains in one call","tags":["Connections"],"description":"$10e","security":[{"widgetJWT":[]},{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domains"],"description":"The body is decoded with unknown fields REJECTED, so the properties below are exactly the accepted set.","properties":{"domains":{"type":"array","items":{"type":"string"},"maxItems":200},"batch_id":{"type":"string","description":"correlates every domain connected in one session."},"end_user_ref":{"type":"string","maxLength":256,"description":"Your own id for the customer these domains belong to. Stored on each connection this call creates and echoed back by the connection reads. Set once; it binds widget tokens to the connection, so it is not a name (send `client_label`)."},"client_label":{"type":"string","maxLength":200,"description":"The name of the client these domains are for, such as an agency's client. Trimmed to one line, at most 200 characters, with characters that draw nothing dropped; a name with nothing left stores no name. Stored on each connection this call creates; `PATCH /connections/{id}` changes it later."},"application_id":{"type":"string","description":"API key callers only: create the connections on this application of the key's tenant instead of the key's own. A widget token may only name its own application."}}}}}},"responses":{"200":{"description":"Per-domain results","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/BulkResult"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}}}},"/provider-accounts":{"post":{"operationId":"createProviderAccount","summary":"Connect a provider account with a key","tags":["Provider accounts"],"description":"$10f","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider","credential"],"properties":{"provider":{"type":"string"},"label":{"type":"string"},"access":{"type":"string","enum":["continuous","one_time"],"default":"continuous","description":"`one_time` is the default, and the only access, for a provider whose credential is used once and never kept."},"scope":{"type":"string","enum":["all","selected"]},"domains":{"type":"array","items":{"type":"string"}},"check_domain":{"type":"string","description":"A domain the key manages, read to check the key when the provider cannot list its domains and `scope` is `all`."},"credential":{"type":"object","required":["token"],"properties":{"token":{"type":"string"},"params":{"type":"object","additionalProperties":{"type":"string"}}}}}}}}},"responses":{"201":{"description":"The account, and the provider's domains when it lists them","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"$ref":"#/components/schemas/ProviderAccount"},"zones":{"type":"array","items":{"type":"string"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"description":"The provider refused the key (`ProviderAuthenticationError`), or `continuous` access for a credential that is used once and never kept (`use_once_credential`), or a chosen Porkbun domain is not opted in to API access (`porkbun_api_access_disabled`, where `400` would otherwise say the key does not reach it)"},"503":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"listProviderAccounts","summary":"Every connected account, with the kept sign-ins and Domain Connect grants","tags":["Provider accounts"],"description":"$110","security":[{"apiKey":[]},{"agentToken":["domains:read"]}],"parameters":[{"name":"provider","in":"query","required":false,"schema":{"type":"string"}},{"name":"domain","in":"query","required":false,"schema":{"type":"string"}},{"name":"application_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"owner","in":"query","required":false,"schema":{"type":"string","enum":["workspace","end_user"]},"description":"Whose keys to list. Without it, every account."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Text to search for in the label, the domains and, for a member, the provider account and end user ids."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200},"description":"The page size. Without it, every account."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"The previous answer's `next_cursor`."}],"responses":{"200":{"description":"The accounts","content":{"application/json":{"schema":{"type":"object","required":["accounts","kept_access","keeping_available"],"properties":{"accounts":{"type":"array","items":{"$ref":"#/components/schemas/ProviderAccount"}},"kept_access":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["sign_in","domain_connect"]},"provider":{"type":"string"},"provider_name":{"type":"string"},"access":{"type":"string","enum":["continuous"]},"connections":{"type":"array","items":{"$ref":"#/components/schemas/AccountConnection"}},"created_at":{"type":"string","format":"date-time"},"last_used_at":{"type":"string","format":"date-time"},"uses":{"type":"array","items":{"type":"string"}}}}},"keeping_available":{"type":"boolean","description":"Whether this deployment can keep keys (a grant encryption key is configured as GRANT_ENCRYPTION_KEY or GRANT_ENCRYPTION_KEYS)."},"end_user_keys":{"type":"object","description":"The keys your customers' own sign-ins made (`owner_kind` `end_user`), counted before `owner`, `q` and paging apply, so a console can show them as one row.","required":["keys","end_users"],"properties":{"keys":{"type":"integer","description":"How many such keys the workspace holds."},"end_users":{"type":"integer","description":"How many customers they belong to (distinct `end_user_ref`; a key with no ref counts as a key only)."}}},"next_cursor":{"type":"string","description":"With `?limit=` only, when more accounts remain. Send it as `?cursor=` for the next page."},"saved_access":{"type":"array","description":"With `?domain=` only. The keys that may act for the domain for the caller, best first, as `GET /connections/{id}/saved-access` lists them.","items":{"$ref":"#/components/schemas/SavedAccess"}}}}}}},"400":{"description":"`owner` is not `workspace` or `end_user`, `limit` is not a whole number from 1 to 200, `cursor` is not one this endpoint returned, or `limit` or `cursor` with `?domain=`"},"401":{"$ref":"#/components/responses/Error"},"403":{"description":"An agent token without `domains:read`, or `?application_id=` naming another application than the agent grant's"},"404":{"description":"`?domain=` with an `application_id` (or an API key's own application) of another workspace, or none"}}}},"/provider-accounts:sign-in":{"post":{"operationId":"startProviderAccountSignIn","summary":"Add a provider account by secure sign in (the console only)","tags":["Provider accounts"],"description":"$111","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider","return_origin","consent_version"],"properties":{"provider":{"type":"string","description":"The provider id. An account has no domain to detect it from."},"application_id":{"type":"string","description":"The application the key is for, one of the workspace's own live applications (a test mode application is refused, and another workspace's is `404`). Left out, the key serves the whole workspace and takes no share."},"return_origin":{"type":"string","description":"Web origin the popup posts its result to; must be on the server's allowlist."},"consent_version":{"type":"string","enum":["cb-1","cb-2","cb-3","cb-4"],"description":"The id of the consent text the person was shown, as for `browser:start`."},"locale":{"type":"string","description":"The language the popup reads in","a plain code such as `en`. Defaults to `en`.":null},"viewport_hint":{"type":"object","description":"The size of the popup's live area, used as for `browser:start`."}}}}}},"responses":{"201":{"description":"The sign in started.","content":{"application/json":{"schema":{"type":"object","required":["session_id","popup_url"],"properties":{"session_id":{"type":"string","description":"The session id, `bs_` and 32 hex characters."},"popup_url":{"type":"string","format":"uri","description":"The popup page; its fragment holds the single use bootstrap code."}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"description":"`browser_account_unavailable` (not the console's own call, or not a caller that may), `browser_customer_present_only` (no known `Origin`), `browser_provider_not_allowed`, `sandbox_not_allowed` (a test mode application) or `forbidden` (a viewer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/provider-accounts:oauth-start":{"post":{"operationId":"startProviderAccountOAuth","summary":"Add a provider account by signing in with the company (the console only)","tags":["Provider accounts"],"description":"$112","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider","return_origin"],"properties":{"provider":{"type":"string","description":"The provider id. An account has no domain to detect it from."},"application_id":{"type":"string","description":"The application the account is for, one of the workspace's own live applications (a test mode application is refused, and another workspace's is `404`). Left out, the account serves the whole workspace."},"return_origin":{"type":"string","description":"Web origin the popup posts its result to; must be on the server's allowlist."}}}}}},"responses":{"200":{"description":"The sign-in started; open `authorize_url` in a popup.","content":{"application/json":{"schema":{"type":"object","required":["authorize_url","provider","flow","callback_origin"],"properties":{"authorize_url":{"type":"string","format":"uri","description":"The company's consent page (or Vercel's install page)."},"provider":{"type":"string"},"flow":{"type":"string","enum":["oauth2","vercel_integration"],"description":"The sign-in the company runs."},"callback_origin":{"type":"string","description":"The origin the result is posted from; accept a message from no other."}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/provider-accounts/{id}":{"get":{"operationId":"getProviderAccount","summary":"One provider account with its domains","tags":["Provider accounts"],"description":"A viewer reads it without `agent_key.account` and `agent_key.session_id`.\n\nFor whoever manages the account (`can_manage`, and never a viewer), it also carries `more_domains`: the domains the key lists at the provider that the workspace has not connected, to offer them with `POST /provider-accounts/{id}/connect`. Listing them is a use of the key, so it is asked of the provider on this read (kept for a minute) and left out for anyone else, for a key an end user's secure sign-in made, and for an account with no usable key. The read changes nothing: a key the provider refuses, or a list that fails, leaves `more_domains` out and the account as it was.","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"The account","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"$ref":"#/components/schemas/ProviderAccount"}}}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"updateProviderAccount","summary":"Change an account's label, access, scope or the applications it is shared with","tags":["Provider accounts"],"description":"$113","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","description":"The account's name: one to 80 characters once trimmed, with no control or invisible character in it (`400` `invalid_request` otherwise). Whoever manages the account may change it, as for `access`, `scope` and `domains` (`403` otherwise)."},"access":{"type":"string","enum":["continuous","one_time"]},"scope":{"type":"string","enum":["all","selected"],"description":"`all` widens a `selected` account; for a key made at a secure sign-in it needs the provider to list the key's domains (`422` `scope_all_needs_list`)."},"domains":{"type":"array","items":{"type":"string"},"description":"The whole set of domains a `selected` account may use. A domain it does not hold yet widens the account; for a key made at a secure sign-in each such domain must be one the key reaches (`422` `zone_not_reached`, at most 20 new ones a call). For an account on `all` that is any domain not already in its `domains`, also when the call goes back to `selected`."},"application_ids":{"type":"array","maxItems":100,"description":"The other applications of the workspace the key is shared with, as a whole: it replaces the set. Admin or owner only.","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"The account","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"$ref":"#/components/schemas/ProviderAccount"}}}}}},"400":{"description":"`invalid_request` (a `label` that is empty once trimmed, longer than 80 characters or holds a control or invisible character, or a change that leaves no domain and no scope `all`) or `too_many_domains_to_check`. Nothing is stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"description":"`forbidden`: a viewer, or a member who did not connect the account asking to change its `label`, `access`, `scope` or `domains`; anyone but an admin or an owner asking for `application_ids`, or to change a key an end user's sign-in made; or a change that would widen such a key. Nothing is stored and nothing is audited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"description":"`zone_not_reached` (a domain added is not one the key reaches; `domains` names them), `scope_all_needs_list`, `serves_every_application`, `use_once_credential` or `ProviderAuthenticationError`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainsRefusedError"}}}},"429":{"$ref":"#/components/responses/ReachQuota"},"503":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"revokeProviderAccount","summary":"Revoke an account","tags":["Provider accounts"],"description":"Deletes the key and the account. Its domains stay connected and served, without continuous access; each domain's timeline records it. The answer says what that leaves: `used_by` is how many domains used the account, and `revoke_url` is the provider's page where the key itself is deleted. It deletes CustomDomain™'s copy only, for a key a person pasted as for a lasting API key the cloud browser's agent made: the key lives at the provider until it is deleted there (no provider documents an API that revokes one), and the application receives `credential.removed` for a key the agent made. Removing an account takes whoever manages it, like every other change to it: an admin, an owner or the member who connected it (`can_manage`), and for a key a customer's secure sign-in made, which no member connected, an admin or an owner. Anyone else, a viewer included, gets `403`, and nothing is deleted or detached.","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"revoked":{"type":"boolean"},"used_by":{"type":"integer","description":"How many domains used the account. They stay connected, each with a timeline event, without continuous access."},"domains_kept_connected":{"type":"integer","description":"The same number as `used_by`, kept for older integrations."},"revoke_url":{"type":"string","format":"uri","description":"The provider's page where the key itself is deleted: the page the agent's own sign-in named for a key it made, else the provider's key page. Absent when the provider has none on file."}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/provider-accounts/{id}/zones":{"post":{"operationId":"listProviderAccountZones","summary":"The domains the account's key can reach","tags":["Provider accounts"],"description":"Lists the provider's domains with the kept key. `listed` is false for a provider that cannot list them. A refused key flags the account `needs_reconnect`. It takes an admin, an owner or the member who connected the account (`can_manage`), as connecting domains with it does; anyone else gets `403`. A one time account past its hour answers `409`, and its key is deleted then if the hourly cleanup has not deleted it yet. A key an end user's secure sign-in made in the widget answers `403`: it never lists the domains of the end user's account. The list is one read of the workspace's hourly budget of reach checks: once it is spent the call answers `429` `reach_quota` with `Retry-After` and asks the provider nothing.","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"The domains","content":{"application/json":{"schema":{"type":"object","properties":{"zones":{"type":"array","items":{"type":"string"}},"listed":{"type":"boolean"},"message":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"description":"The provider refused the key; the account is flagged `needs_reconnect`"},"429":{"$ref":"#/components/responses/ReachQuota"},"503":{"$ref":"#/components/responses/Error"}}}},"/provider-accounts/{id}/connect":{"post":{"operationId":"connectWithProviderAccount","summary":"Connect domains with the account","tags":["Provider accounts"],"description":"$114","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domains"],"properties":{"application_id":{"type":"string","description":"The application for a domain that names none of its own. Leave it out when every domain names its own or is already held by an application of the workspace: that application is the default."},"domains":{"type":"array","description":"The domains to connect, at most 200. Each is a name, or an object naming the application that one domain goes into.","items":{"oneOf":[{"type":"string"},{"type":"object","required":["domain"],"additionalProperties":false,"properties":{"domain":{"type":"string"},"application_id":{"type":"string","description":"The application this domain goes into, one the key serves."}}}]}},"www_redirect":{"type":"boolean"},"client_label":{"type":"string","maxLength":200,"description":"The name of the client every domain of this call is for, as `POST /connections:bulk` takes it (a name with nothing readable left stores no name). A domain the application already has keeps its own name."}}}}}},"responses":{"200":{"description":"Per domain results and the account","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/AccountConnectResult"}},"account":{"$ref":"#/components/schemas/ProviderAccount"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/ReachQuota"},"503":{"$ref":"#/components/responses/Error"}}}},"/provider-accounts/{id}/reconnect":{"post":{"operationId":"reconnectProviderAccount","summary":"Give an account a new key","tags":["Provider accounts"],"description":"$115","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["api_key","secure_sign_in"],"default":"api_key","description":"How the key is renewed. `api_key` takes `credential` (required then); `secure_sign_in` takes the sign in's fields and no key."},"access":{"type":"string","enum":["continuous","one_time"],"description":"`api_key` only."},"check_domain":{"type":"string","description":"`api_key` only: a domain the key manages, read to check the key when the provider cannot list its domains."},"credential":{"type":"object","required":["token"],"description":"`api_key` only, and required for it.","properties":{"token":{"type":"string"},"params":{"type":"object","additionalProperties":{"type":"string"}}}},"return_origin":{"type":"string","description":"`secure_sign_in` only, required: web origin the popup posts its result to; must be on the server's allowlist."},"consent_version":{"type":"string","enum":["cb-1","cb-2","cb-3","cb-4"],"description":"`secure_sign_in` only, required: the id of the consent text the person was shown, as for `browser:start`."},"locale":{"type":"string","description":"`secure_sign_in` only: the language the popup reads in. Defaults to `en`."},"viewport_hint":{"type":"object","description":"`secure_sign_in` only: the size of the popup's live area, used as for `browser:start`."}}}}}},"responses":{"200":{"description":"The account (`api_key`).","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"$ref":"#/components/schemas/ProviderAccount"}}}}}},"201":{"description":"The sign in started (`secure_sign_in`).","content":{"application/json":{"schema":{"type":"object","required":["session_id","popup_url"],"properties":{"session_id":{"type":"string","description":"The session id, `bs_` and 32 hex characters."},"popup_url":{"type":"string","format":"uri","description":"The popup page; its fragment holds the single use bootstrap code."}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"description":"`forbidden` (a viewer, a member who did not connect the account, or a key a customer's own sign in made, for `secure_sign_in`), `browser_account_unavailable` (`secure_sign_in` from anything but the console's own call), `browser_provider_not_allowed` or `workspace_suspended`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"description":"The provider refused the key (`ProviderAuthenticationError`), or `continuous` access for a credential that is used once and never kept (`use_once_credential`), or a chosen Porkbun domain is not opted in to API access (`porkbun_api_access_disabled`, where `400` would otherwise say the key does not reach it)"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/provider-accounts/{id}:check":{"post":{"operationId":"checkProviderAccount","summary":"Check an account's key now","tags":["Provider accounts"],"description":"$116","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"The account after the check, and what the check found.","content":{"application/json":{"schema":{"type":"object","required":["account","result"],"properties":{"account":{"$ref":"#/components/schemas/ProviderAccount"},"result":{"type":"string","enum":["ok","refused","unreachable"],"description":"What the check found."},"message":{"type":"string","description":"For `unreachable`, the provider's own words, on one line."}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"The account holds no key, it is a one time account, nothing could be read the key against (`nothing_to_check`), or it changed while it was checked"},"429":{"description":"`rate_limited`: this account's key was checked less than a minute ago (`Retry-After: 60`), or `reach_quota`: the workspace has made as many reach checks at providers as it may this hour (`Retry-After` is the seconds until the hour ends).","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the key can be checked again."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/providers/{provider}/zones:list":{"post":{"operationId":"listProviderZones","summary":"Enumerate the connectable domains a provider credential controls","tags":["Providers"],"description":"For the bulk-connect picker. The credential is used once to list zones and is never persisted here. `422` (`list_not_supported`) when the adapter can't enumerate zones; the console degrades to single-domain connect.","security":[{"widgetJWT":[]}],"parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["credential"],"properties":{"credential":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"Scoped provider API token; used once, never persisted."}}}}}}}},"responses":{"200":{"description":"Zones","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string"},"zones":{"type":"array","items":{"type":"string"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"422":{"description":"The provider can't enumerate zones","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","examples":["list_not_supported"]},"provider":{"type":"string"},"message":{"type":"string"}}}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/registrar/checkout":{"post":{"operationId":"startDomainCheckout","summary":"Start an embedded payment to buy a domain at retail","tags":["Registrar"],"description":"$117","security":[{"widgetJWT":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain","buyer","return_url"],"properties":{"domain":{"type":"string"},"buyer":{"type":"object","required":["email"],"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"country":{"type":"string","description":"ISO 3166-1 alpha-2."}}},"return_url":{"type":"string","format":"uri"},"ui_mode":{"type":"string","enum":["embedded","elements"],"default":"embedded","description":"How the payment is shown. Leave it out (or send null or an empty string) for embedded: a domain payment has no redirect flow. Never send `hosted`."}}}}}},"responses":{"200":{"description":"Stripe checkout session (embedded or elements)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSession"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/BillingRequired"},"403":{"$ref":"#/components/responses/ForbiddenOrSuspended"},"503":{"$ref":"#/components/responses/Error"}}}},"/registrar/fulfill":{"post":{"operationId":"fulfillDomainPurchase","summary":"Finalize a domain purchase after the embedded payment completes","tags":["Registrar"],"description":"Verifies the session, registers the domain, captures the charge, and auto-connects the domain. Idempotent per session id (the Stripe webhook drives the same path server-side, so a closed tab never strands a paid session). `201` on first fulfillment, `200` on an idempotent replay. Exactly one caller fulfills a session: the first to claim its order registers the domain and captures the charge, and a caller that arrives while it is still working waits briefly, then gets that result or a `409` with code `fulfillment_in_progress`. A `409` never releases the authorization; retry the call, or read `GET /v1/sell/orders/{id}`, to see the outcome.","security":[{"widgetJWT":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["session_id"],"properties":{"session_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Already fulfilled (idempotent replay)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellOrder"}}}},"201":{"description":"Purchased","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellOrder"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"409":{"description":"Another call is still completing this purchase (code: fulfillment_in_progress). The payment stays authorized and `order` is the order as it stands (status `purchasing`). Also `conflict` when the order can no longer be fulfilled (for example `expired`); the card was not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentInProgressError"}}}},"502":{"description":"Registrar registration failed after payment authorization; the card authorization was released (code: registration_failed).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/sell/orders":{"get":{"operationId":"listSellOrders","summary":"List the calling application's domain-purchase orders, newest first","description":"Every order the application recorded (quoted, purchasing, purchased, transferred, failed, or expired). `purchasing` is an order being registered right now, after its payment was authorized. A quote-only order that was never paid for is expired by the hourly reaper after 24 hours (status `expired`, with a `purchase.confirmation.expired` webhook), so \"quoted\" always means recent intent.\n\nWith a tenant API key it lists the orders of every application of the tenant, or of one with `app_id` (another tenant's id answers `404`). A widget token minted with scope `app`, or a delegated agent token with `domains:read`, lists its own application's orders.","tags":["Registrar"],"security":[{"widgetJWT":[]},{"apiKey":[]},{"agentToken":["domains:read"]}],"parameters":[{"name":"app_id","in":"query","required":false,"description":"With a tenant API key, list the orders of this one application of the tenant.","schema":{"type":"string"}}],"responses":{"200":{"description":"Orders","content":{"application/json":{"schema":{"type":"object","required":["orders","count"],"properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/SellOrderView"}},"count":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/sell/orders/{id}":{"get":{"operationId":"getSellOrder","summary":"Read a persisted domain-purchase order's status by id","tags":["Registrar"],"description":"A widget token or a delegated agent token (`domains:read`) reads an order of its own application; a tenant API key reads an order of any of its applications. An order of another application answers `404`.","security":[{"widgetJWT":[]},{"apiKey":[]},{"agentToken":["domains:read"]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellOrderView"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/oauth/agent/register":{"servers":[{"url":"https://api.customdomain.ai","description":"Hosted control-plane (the origin, not /v1)"}],"post":{"operationId":"registerAgentClient","summary":"Register an agent as an OAuth client","tags":["Agents"],"description":"Dynamic Client Registration (RFC 7591). An AI assistant registers itself as a public client (PKCE, no secret) and can do nothing until a person approves a grant for it in the console. Registration is open on purpose, so it is bounded: a per-IP hourly budget on top of the global limit, and a client that nobody ever approves into a workspace is deleted after a while. Other client metadata (`client_uri`, `logo_uri`, `scope`, `contacts`, ...) is accepted and ignored. A `client_name` that claims a well known brand (Claude, ChatGPT, ...) is refused unless every redirect host belongs to that brand or is a loopback address. Errors use the RFC 7591 envelope.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentClientRegistration"}}}},"responses":{"201":{"description":"The registered client","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentClient"}}}},"400":{"description":"`invalid_client_metadata` (a bad or impersonating name, grant or response types without the authorization code grant) or `invalid_redirect_uri` (none, more than 10, a fragment, user information, or http on a host that is not loopback).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/oauth/agent/authorize":{"servers":[{"url":"https://api.customdomain.ai","description":"Hosted control-plane (the origin, not /v1)"}],"get":{"operationId":"authorizeAgent","summary":"Start an agent authorization (code with PKCE)","tags":["Agents"],"description":"The authorization endpoint. A browser is sent here by an agent; the request is validated (the client, the exact redirect URI, S256 PKCE, the scopes, the resource) and the browser is redirected to the console, where a signed in owner or admin sees what the agent asks for and where its code would go, and approves or denies. The authorization code goes to the redirect URI and is exchanged at `POST /oauth/agent/token`. A request with an unregistered or mismatched redirect URI is refused without redirecting. `client_id` is a registered client or an https URL of a Client ID Metadata Document.","security":[],"parameters":[{"name":"client_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"redirect_uri","in":"query","required":true,"schema":{"type":"string","format":"uri"}},{"name":"response_type","in":"query","required":true,"schema":{"type":"string","enum":["code"]}},{"name":"code_challenge","in":"query","required":true,"description":"BASE64URL(SHA-256(code_verifier)).","schema":{"type":"string"}},{"name":"code_challenge_method","in":"query","required":true,"schema":{"type":"string","enum":["S256"]}},{"name":"scope","in":"query","required":true,"description":"Space separated scopes from `domains:read`, `domains:connect`, `domains:disconnect` and `domains:purchase`. The person may approve fewer.","schema":{"type":"string","example":"domains:read domains:connect"}},{"name":"state","in":"query","required":false,"schema":{"type":"string"}},{"name":"resource","in":"query","required":false,"description":"RFC 8707. The resource the token is for: the MCP endpoint (`https://mcp.customdomain.ai/mcp`, the default) or this API's origin. Anything else is `invalid_target`. The access token carries it as `aud`.","schema":{"type":"string","format":"uri"}}],"responses":{"302":{"description":"Redirect to the console consent screen","headers":{"Location":{"schema":{"type":"string","format":"uri"}}}},"400":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/oauth/agent/token":{"servers":[{"url":"https://api.customdomain.ai","description":"Hosted control-plane (the origin, not /v1)"}],"post":{"operationId":"exchangeAgentToken","summary":"Exchange an authorization code or a refresh token for an access token","tags":["Agents"],"description":"`grant_type=authorization_code` (with the PKCE `code_verifier`) or `grant_type=refresh_token`. The access token is an ES256 JWT that lives 15 minutes and is verified locally against `/.well-known/jwks.json`; it carries the tenant, the application the grant is bound to, the grant, the scopes and `aud`. A refresh token rotates: every refresh returns a new one and retires the old, and presenting a retired one again revokes the whole grant (a client racing itself within ten seconds is only refused). Errors use the RFC 6749 envelope.","security":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/AgentTokenRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/AgentTokenRequest"}}}},"responses":{"200":{"description":"The tokens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTokenResponse"}}}},"400":{"description":"`invalid_request`, `invalid_grant` (a code or refresh token that is invalid, expired, spent or revoked, a failed PKCE check, a grant that is no longer active), `invalid_target` (a resource that is not the one approved) or `unsupported_grant_type`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"503":{"description":"Agent access is not enabled on this deployment (`temporarily_unavailable`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}}}}},"/oauth/agent/revoke":{"servers":[{"url":"https://api.customdomain.ai","description":"Hosted control-plane (the origin, not /v1)"}],"post":{"operationId":"revokeAgentToken","summary":"Revoke an agent's access with its refresh token","tags":["Agents"],"description":"RFC 7009. Revokes the grant behind a refresh token, so the agent's access ends within one access token lifetime (15 minutes at most). It answers `200` for a token it does not know, so it cannot be used to find out which tokens exist. The workspace's owners and admins are told once.","security":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"The refresh token."}}}},"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"The refresh token."}}}}}},"responses":{"200":{"description":"Revoked, or the token was not known"},"400":{"description":"`invalid_request`: no token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"503":{"description":"Agent access is not enabled on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}}}}},"/agent/consent-request/{id}":{"get":{"operationId":"getAgentConsentRequest","summary":"Read a pending agent authorization, for the consent screen","tags":["Agents"],"description":"What the console shows a signed in owner before they approve an agent: the client's name, where its authorization code would go (`redirect_host`), whether that destination is a known assistant's own (`verified`, `verified_as`) or the person's own computer (`local`), whether the name imitates a brand it does not belong to (`imitates`; such a request cannot be approved), how the client identified itself, and the scopes asked for. The unguessable request id is the capability: it needs no other credential and reveals only this.","security":[],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"The pending request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentConsentRequest"}}}},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"cancelAgentConsentRequest","summary":"Deny a pending agent authorization","tags":["Agents"],"description":"Consumes the request so it can no longer be approved, from this tab or any other. Idempotent, and like the read it needs no credential: the request id is the capability, and cancelling is all it allows.","security":[],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"204":{"description":"Denied"},"503":{"$ref":"#/components/responses/Error"}}}},"/agent/consent":{"post":{"operationId":"approveAgent","summary":"Approve an agent and mint its authorization code","tags":["Agents"],"description":"Called by the console's server after a person signs in and approves, with that member's tenant API key (a widget token is refused, because it lives in browsers). The key's member needs `agent:manage` (owners and admins), and `member_id` must belong to the workspace. The approved scopes are a subset of what was requested. The grant is bound to one `application_id` of the workspace. An agent whose code goes to an unverified host needs `acknowledged_unverified: true`, and one whose name imitates a brand is refused (`403`). `domains:purchase` also needs a `spend_cap_cents` and a saved card. Persistent access is the default; `persist: false` ends it after `expires_days`. The authorization code is single use and is exchanged at `POST /oauth/agent/token`.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentConsentApproval"}}}},"responses":{"200":{"description":"The redirect for the agent, with its code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentConsentResult"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/agent/grants":{"get":{"operationId":"listAgentGrants","summary":"List the workspace's agent grants","tags":["Agents"],"description":"Every grant of the workspace with the current month's spend, for the console's manage screen. Needs a tenant API key held by an owner or admin (`agent:manage`). Refresh tokens are never returned.","security":[{"apiKey":[]}],"responses":{"200":{"description":"The grants","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentGrantList"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/agent/grants/{id}":{"delete":{"operationId":"revokeAgentGrant","summary":"Revoke an agent's access","tags":["Agents"],"description":"Ends the grant and kills its refresh tokens; the agent's access token stops working within its 15 minute life. A grant of another workspace answers `404`. The workspace's owners and admins are told once (a repeat is quiet), and the audit log records `agent.revoked`. Needs `agent:manage`.","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"204":{"description":"Revoked"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/config":{"get":{"operationId":"getConfig","summary":"Public service discovery (advertised products and version)","tags":["Meta"],"security":[],"responses":{"200":{"description":"Service capabilities","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"string"},"env":{"$ref":"#/components/schemas/Environment"},"version":{"type":"string"},"api_version":{"type":"string","examples":["v1"]},"products":{"type":"array","description":"The products THIS deployment actually serves, not the full catalog. \"connect\" and \"mcp\" are always present; \"secure\" appears only when SECURE_ENABLED is set, \"power\" only when POWER_ENABLED is set, \"sell\" only when a registrar is configured, and \"monitor\" only when a DNS resolver is wired. Absent products answer 503 not-configured on every route. Per-tenant plan entitlements are not reflected here; this endpoint is unauthenticated.","items":{"type":"string"},"examples":[["connect","secure","sell","power","monitor","mcp"]]}}}}}}}}}},"components":{"securitySchemes":{"managementKey":{"type":"http","scheme":"bearer","description":"Operator management key. Gates provisioning + reads across tenants."},"provisionSecret":{"type":"apiKey","in":"header","name":"X-Provision-Secret","description":"Narrow secret held by the customer console's server, for signup provisioning and its other server to server calls (also accepted as a Bearer token, except on POST /audit, where a Bearer is always a tenant credential)."},"apiKey":{"type":"http","scheme":"bearer","description":"Long-lived tenant API key, cd_live_… (production) or cd_test_… (staging, development), stored hashed. Keys created before the switch to cd_ start with sk_live_… / sk_test_… and are still accepted. Scoped to the owning application's tenant."},"widgetJWT":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Short-lived widget JWT minted server-side via POST /v1/tokens. Scoped to one application (and optionally one domain)."},"browserSession":{"type":"http","scheme":"bearer","description":"The session token of one cloud browser sign in, returned by `POST /browser-sessions:redeem`. It binds one session, one connection and one workspace, lives at most as long as the session, and stops working the moment the session ends. It lives in the popup's memory only."},"agentToken":{"type":"oauth2","description":"A delegated agent access token: an ES256 JWT that lives 15 minutes, sent as a bearer token. A person approves an agent in the console and the agent exchanges its authorization code (with PKCE) at the token endpoint. The token carries the workspace, the one application the grant is bound to, the grant, the approved scopes and its audience, and is verified against `/.well-known/jwks.json`. A route that accepts it lists the scope it needs; a token without the scope is refused with `403`, and a connection or order of another application answers `404`.","flows":{"authorizationCode":{"authorizationUrl":"https://api.customdomain.ai/oauth/agent/authorize","tokenUrl":"https://api.customdomain.ai/oauth/agent/token","refreshUrl":"https://api.customdomain.ai/oauth/agent/token","scopes":{"domains:read":"Look at availability, connections, records, certificates, diagnoses, orders and the billing standing.","domains:connect":"Connect a domain, recheck it, reapply its records and start a one click setup.","domains:disconnect":"Remove a connected domain. The call must name the domain.","domains:purchase":"Buy a domain, up to the grant's monthly spend cap."}}}}},"parameters":{"Id":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"BrowserSessionId":{"name":"sid","in":"path","required":true,"description":"The cloud browser session id, `bs_` and 32 hex characters.","schema":{"type":"string"}},"ActorEmail":{"name":"X-Actor-Email","in":"header","required":false,"description":"The email of the person acting through the owner dashboard, recorded as the actor on the billing audit trail (the management key names no one). Read only on these operator routes. Absent or not an email: the actor is recorded as \"owner dashboard\".","schema":{"type":"string","format":"email"}}},"responses":{"Error":{"description":"Error envelope: {code, title, details}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ReachQuota":{"description":"`reach_quota`: the workspace has made as many reads at DNS providers, to find out what a key reaches, as it may this hour (the saved key resolver's reads, a key's reach check when its scope is widened, the list of a key's domains and Check now share one budget). Nothing was read at the provider, nothing changed and nothing was spent from the hour. `Retry-After` is the seconds until the hour ends, when the count starts again.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the hour ends and the workspace's count starts again."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"reach_quota","title":"Too many checks at DNS providers this hour.","details":"this workspace has made as many checks of its keys at DNS providers as it may in an hour; nothing was changed, try again in about 40 minutes"}}}},"RedirectsBusy":{"description":"`redirects_busy`: another change to this workspace's forwarding is still being saved (redirect changes of one workspace are made one at a time), and this one waited for it in vain. Nothing was changed; send it again after the `Retry-After` seconds. `service_unavailable`: edge serving is off in this deployment, so a forward cannot be set.","headers":{"Retry-After":{"description":"Seconds to wait before sending the call again (on `redirects_busy`).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ForbiddenOrSuspended":{"description":"`forbidden`: the credential may not do this. `workspace_suspended`: CustomDomain™ support suspended the workspace. While it is suspended, new connections (one by one or in bulk, where each domain fails on its own), every connect step on a domain it already has (the credentialed apply, a provider sign in to connect, the cloud browser, Domain Connect, the Route 53 access role, the hosted zone and `:reapply`) and the start of a domain purchase are refused; reads, rechecks, removals and the sign in to remove a domain keep working, and domains already connected keep their records. A connect-scoped widget token, the tenant's own end user, gets `402 connections_unavailable` instead, the neutral answer it gets for a billing refusal. Support resumes the workspace; nothing in the API does.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"workspace_suspended","title":"This workspace is suspended.","details":"New domains, connect steps and domain purchases are refused while CustomDomain™ support has this workspace suspended. Contact support to have it resumed."}}}},"ForbiddenOrWrongEndUser":{"description":"`forbidden`: the credential may not do this. `token_wrong_end_user`: a widget token that is not this connection's end user (the connection names another end user than the token's `end_user_ref`, or names one while the token names none); nothing is read or changed, and the answer shows nothing of the connection. Mint the token with the end user's `end_user_ref`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ForbiddenSuspendedOrWrongEndUser":{"description":"`forbidden`: the credential may not do this. `workspace_suspended`: see the `ForbiddenOrSuspended` response. `token_wrong_end_user`: a widget token that is not this connection's end user (the connection names another end user than the token's `end_user_ref`, or names one while the token names none); nothing is read, written or changed, and the answer shows nothing of the connection. Mint the token with the end user's `end_user_ref`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"BillingRequired":{"description":"$118","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"billing_required","title":"An active subscription is needed to connect new domains.","details":"This workspace has not started its subscription yet. Domains that are already connected keep working. An owner or admin can set up billing at https://app.customdomain.ai/app/billing."}}}},"AdminBillingTenant":{"description":"The workspace after the action, with its invoices and audit trail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminBillingTenantDetail"}}}}},"schemas":{"EmailSender":{"type":"object","required":["application_id","mode","smtp_host","smtp_port","smtp_username","password_set","tls","from_address","from_name","reply_to","verified_at","last_error","last_error_at"],"properties":{"application_id":{"type":"string"},"mode":{"type":"string","enum":["default","smtp","none"]},"smtp_host":{"type":"string"},"smtp_port":{"type":"integer"},"smtp_username":{"type":"string"},"password_set":{"type":"boolean","description":"Whether a password is stored. The password itself is never returned."},"tls":{"type":"string","enum":["implicit","starttls"]},"from_address":{"type":"string"},"from_name":{"type":"string"},"reply_to":{"type":"string"},"verified_at":{"type":["string","null"],"format":"date-time"},"last_error":{"type":"string","description":"The last failure, with no secret in it. Empty after a success."},"last_error_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"EmailSenderInput":{"type":"object","required":["mode"],"additionalProperties":false,"properties":{"mode":{"type":"string","enum":["default","smtp","none"]},"smtp_host":{"type":"string","description":"A public host name or address. Private, loopback, link-local and metadata addresses are refused."},"smtp_port":{"type":"integer","enum":[25,465,587,2525]},"smtp_username":{"type":"string"},"smtp_password":{"type":"string","description":"Write only. Omit to keep the stored password."},"tls":{"type":"string","enum":["implicit","starttls"],"description":"implicit on port 465, starttls on the others. Defaults to starttls."},"from_address":{"type":"string","description":"A plain address such as hello@example.com. Required for smtp."},"from_name":{"type":"string","maxLength":100},"reply_to":{"type":"string"}}},"Error":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","description":"stable machine code, e.g. invalid_request, unauthorized, not_found, service_unavailable, internal_error"},"title":{"type":"string","description":"human-readable summary"},"details":{"type":"string","description":"optional extra context"}}},"FulfillmentInProgressError":{"description":"The error envelope of `POST /v1/registrar/fulfill`'s `409`, plus the order as it stands.","allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"order":{"$ref":"#/components/schemas/SellOrderView"}}}]},"DomainsRefusedError":{"description":"The error envelope of a refusal that is about domains the caller named, plus those domains: `zone_not_reached` of `PATCH /v1/provider-accounts/{id}` (the domains added that the key does not reach) and `different_account` of `POST /v1/browser-sessions/{sid}:keep` for a renewal (the domains the account holds that the new key does not list).","allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"domains":{"type":"array","items":{"type":"string"},"description":"The domains the refusal is about. Absent for any other refusal."}}}]},"Environment":{"type":"string","enum":["production","staging","development"]},"Role":{"type":"string","enum":["owner","admin","member","viewer"]},"PlanId":{"type":"string","description":"`free` is retired: legacy workspaces still carry it until they subscribe, and it cannot be bought or assigned.","enum":["starter","startup","growth","premium","enterprise","free"]},"Plan":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/PlanId"},"name":{"type":"string"},"price_cents":{"type":"integer","description":"Monthly price in US cents; 0 when not public."},"public_price":{"type":"boolean"},"domains_per_year":{"type":"integer","description":"The marketed annual allowance."},"domains_per_month":{"type":"integer","description":"`domains_per_year` ceiling-divided by 12 (0 = unlimited). It is the enforced allowance only when `quota_window_months` is 1; read `quota` for the enforced number."},"quota":{"type":"integer","description":"The enforced allowance: new domains counted over `quota_window_months` calendar months ending with the current one. `starter` is 10 over 12 months; the other plans are their monthly share over 1. 0 = unlimited."},"quota_window_months":{"type":"integer","description":"How many calendar months `quota` counts over, ending with the current one: 12 on `starter` (and the retired `free`), 1 on every other plan."},"metered":{"type":"boolean"},"overage_increment":{"type":"integer"},"motion":{"type":"string","enum":["self_serve","contact_sales"]},"entitlements":{"type":"object"},"hard_cap":{"type":"boolean","description":"Connections past `quota` are refused (`starter`) rather than recorded as overage."},"trial_days":{"type":"integer","description":"The trial a new workspace's first subscription to this plan starts with (0 for contact sales)."},"default":{"type":"boolean","description":"The plan preselected for a new workspace (`starter`)."}}},"BillingState":{"type":"string","description":"A workspace's billing state, evaluated from its record and the clock. `trialing` and `active` are a running Stripe subscription; `past_due` is a failed payment Stripe is still retrying (nothing is refused); `grace` is a legacy Free workspace (or an operator extension) inside its grace period; `legacy_free` is a Free workspace whose grace has not started; `comped` is an operator comp; `blocked` and `canceled` refuse new connections (`402 billing_required`) while live domains keep working. A new workspace (`blocked`, reason `setup_required`) is refused only once its first domain is connected: see `first_domain_free`.","enum":["trialing","active","past_due","grace","blocked","comped","canceled","legacy_free"]},"BillingNotice":{"type":"object","required":["role","can_manage","configured","attention","restricted"],"properties":{"role":{"$ref":"#/components/schemas/Role"},"can_manage":{"type":"boolean","description":"Whether this member holds billing:manage (owners and admins)."},"configured":{"type":"boolean","description":"Whether a workspace can subscribe on this deployment."},"attention":{"type":"boolean","description":"Billing needs an owner or admin: a trial or grace to act on, a failed payment, or a block."},"restricted":{"type":"boolean","description":"New domain connections are refused right now."},"setup_required":{"type":"boolean","description":"Owners and admins only: send them through the billing setup flow."},"first_domain_free":{"type":"boolean","description":"Owners and admins only, and present only when true: this is a new workspace on the first domain free rule. Its first domain connects without a subscription, so `restricted` is false until that domain is connected and true after, and the next one needs the trial. Credentials (an API key, an application) always need it."},"free_domains":{"type":"integer","description":"Owners and admins only, present with `first_domain_free`: how many domains the workspace may connect before it has a subscription. One, unless the operator granted more."},"state":{"$ref":"#/components/schemas/BillingState"},"reason":{"type":"string","description":"Why a restricted workspace is restricted: setup_required, grace_ended, unpaid, comp_ended or canceled."},"plan_id":{"type":"string"},"plan_name":{"type":"string"},"days_left":{"type":"integer","description":"Whole days left in the trial or grace; -1 otherwise."},"trial_ends_at":{"type":["string","null"],"format":"date-time"},"grace_ends_at":{"type":["string","null"],"format":"date-time"},"current_period_end":{"type":["string","null"],"format":"date-time"},"cancel_at_period_end":{"type":"boolean"},"payment_failed":{"type":"boolean"}}},"BillingStanding":{"type":"object","required":["configured","restricted","attention","billing_url"],"properties":{"configured":{"type":"boolean","description":"Whether a workspace can subscribe on this deployment."},"restricted":{"type":"boolean","description":"New domain connections are refused right now."},"first_domain_free":{"type":"boolean","description":"Present only when true: this is a new workspace on the first domain free rule. `restricted` is false until its free domains are connected, and true, with the refusal's words, after."},"free_domains":{"type":"integer","description":"Present with `first_domain_free`: how many domains the workspace may connect before it has a subscription. One, unless the operator granted more."},"attention":{"type":"boolean","description":"Billing needs an owner or admin: a trial or grace to act on, a failed payment, or a block."},"code":{"type":"string","description":"Set when `restricted`: `billing_required`."},"title":{"type":"string","description":"Set when `restricted`: what the refusal says."},"details":{"type":"string","description":"Set when `restricted`: why, and where an owner or admin fixes it."},"billing_url":{"type":"string","description":"Where an owner or admin sets up billing."},"plan":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"hard_cap":{"type":"boolean","description":"Whether the plan refuses new connections at its quota (when the deployment enforces quotas)."}}},"usage":{"type":"object","properties":{"used":{"type":"integer","description":"Domains connected over the quota window: `window_months` calendar months ending with `period`."},"quota":{"type":"integer","description":"What the plan includes over that window (10 over 12 months on `starter`)."},"window_months":{"type":"integer","description":"How many calendar months `used` and `quota` cover: 12 on `starter`, 1 elsewhere."},"period":{"type":"string","description":"The current calendar month, `YYYY-MM` (UTC), the last month of the window."}}}}},"BillingStatus":{"type":"object","properties":{"tenant_id":{"type":"string"},"state":{"$ref":"#/components/schemas/BillingState"},"reason":{"type":"string"},"restricted":{"type":"boolean"},"first_domain_free":{"type":"boolean","description":"Present only when true: a new workspace on the first domain free rule (see `GET /billing/notice`)."},"free_domains":{"type":"integer","description":"Present with `first_domain_free`: how many domains the workspace may connect before it has a subscription."},"attention":{"type":"boolean"},"setup_required":{"type":"boolean"},"days_left":{"type":"integer"},"price_cents":{"type":"integer","description":"What the workspace pays per month (the Stripe amount, else the catalog price)."},"currency":{"type":"string"},"trial_ends_at":{"type":["string","null"],"format":"date-time"},"grace_started_at":{"type":["string","null"],"format":"date-time"},"grace_ends_at":{"type":["string","null"],"format":"date-time"},"current_period_end":{"type":["string","null"],"format":"date-time"},"cancel_at_period_end":{"type":"boolean"},"ended_at":{"type":["string","null"],"format":"date-time"},"comped":{"type":"boolean"},"comped_until":{"type":["string","null"],"format":"date-time"},"payment_failed":{"type":"boolean"},"payment_failed_at":{"type":["string","null"],"format":"date-time"},"has_billing_account":{"type":"boolean"},"portal_available":{"type":"boolean"},"can_change_plan":{"type":"boolean"},"mode":{"type":"string","enum":["test","live",""]},"plan":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/PlanId"},"name":{"type":"string"},"price_cents":{"type":"integer"},"public_price":{"type":"boolean"},"domains_per_year":{"type":"integer"},"domains_per_month":{"type":"integer"},"quota":{"type":"integer","description":"The enforced allowance over `quota_window_months` (see `Plan`)."},"quota_window_months":{"type":"integer","description":"12 on `starter`, 1 elsewhere."},"hard_cap":{"type":"boolean"},"retired":{"type":"boolean"}}},"next_charge":{"type":["object","null"],"properties":{"at":{"type":"string","format":"date-time"},"amount_cents":{"type":"integer"},"currency":{"type":"string"}}},"checkout":{"type":"object","description":"What a checkout started now would give.","properties":{"available":{"type":"boolean"},"trial_days":{"type":"integer"},"trial_end":{"type":["string","null"],"format":"date-time"},"first_charge_at":{"type":"string","format":"date-time"},"default_plan":{"$ref":"#/components/schemas/PlanId"}}},"usage":{"type":"object","description":"Usage over the plan's quota window: this calendar month, or the 12 months ending with it on `starter`.","properties":{"used":{"type":"integer","description":"Domains connected over the window."},"quota":{"type":"integer","description":"What the plan includes over the window."},"window_months":{"type":"integer","description":"How many calendar months the window covers: 12 on `starter`, 1 elsewhere."},"period_start":{"type":"string","format":"date-time","description":"The first day of the window."},"period_end":{"type":"string","format":"date-time","description":"The end of the current month."}}},"payment_method":{"type":["object","null"],"description":"The payment method the workspace is charged on, or null when Stripe holds none. A card has its brand, last four digits and expiry, and names the wallet when it was paid through Apple Pay or Google Pay. A Link account has the email of the account (Stripe never shows the card behind it). Cash App Pay has only its type.","properties":{"type":{"type":"string","enum":["card","link","cashapp"]},"brand":{"type":"string"},"last4":{"type":"string"},"exp_month":{"type":"integer"},"exp_year":{"type":"integer"},"wallet":{"type":"string","enum":["apple_pay","google_pay"],"description":"The wallet a card was paid through, when it was."},"email":{"type":"string","description":"The email of the Link account (type link)."}}}}},"Invoice":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string","description":"Stripe invoice status: draft, open, paid, uncollectible or void."},"amount_due_cents":{"type":"integer"},"amount_paid_cents":{"type":"integer"},"currency":{"type":"string"},"created_at":{"type":["string","null"],"format":"date-time"},"hosted_invoice_url":{"type":["string","null"]},"invoice_pdf":{"type":"string"}}},"AdminBillingSummary":{"type":"object","required":["currency","mrr_cents","counts"],"properties":{"currency":{"type":"string"},"mrr_cents":{"type":"integer"},"counts":{"type":"object","required":["trialing","active","past_due","grace","blocked","comped","canceled","legacy_free"],"properties":{"trialing":{"type":"integer"},"active":{"type":"integer"},"past_due":{"type":"integer"},"grace":{"type":"integer"},"blocked":{"type":"integer"},"comped":{"type":"integer"},"canceled":{"type":"integer"},"legacy_free":{"type":"integer"}}},"tenants":{"type":"integer"},"paying":{"type":"integer"},"can_subscribe":{"type":"boolean"},"enforcement":{"type":"boolean","description":"Whether BILLING_REQUIRE_SUBSCRIPTION is on."},"mode":{"type":"string"},"trial_days":{"type":"integer"},"generated_at":{"type":"string","format":"date-time"},"starter_price_on":{"type":"boolean"}}},"AdminBillingTenant":{"type":"object","required":["tenant_id","name","owner_email","plan_id","plan_name","price_cents","status","trial_ends_at","grace_ends_at","current_period_end","cancel_at_period_end","comped_until","stripe_customer_id","stripe_subscription_id","usage","created_at"],"properties":{"tenant_id":{"type":"string"},"name":{"type":"string"},"owner_email":{"type":"string"},"plan_id":{"type":"string"},"plan_name":{"type":"string"},"price_cents":{"type":"integer"},"status":{"$ref":"#/components/schemas/BillingState"},"trial_ends_at":{"type":["string","null"],"format":"date-time"},"grace_ends_at":{"type":["string","null"],"format":"date-time"},"current_period_end":{"type":["string","null"],"format":"date-time"},"cancel_at_period_end":{"type":"boolean"},"comped_until":{"type":["string","null"],"format":"date-time"},"stripe_customer_id":{"type":["string","null"]},"stripe_subscription_id":{"type":["string","null"]},"usage":{"type":"object","description":"Usage over the plan's quota window (12 months on `starter`, the current month elsewhere).","properties":{"used":{"type":"integer"},"quota":{"type":"integer"},"window_months":{"type":"integer"},"period_start":{"type":["string","null"],"format":"date-time"},"period_end":{"type":["string","null"],"format":"date-time"}}},"created_at":{"type":["string","null"],"format":"date-time"},"reason":{"type":"string"},"restricted":{"type":"boolean"},"comped":{"type":"boolean"},"comp_reason":{"type":"string"},"payment_failed":{"type":"boolean"},"stripe_status":{"type":"string"},"currency":{"type":"string"},"grace_started_at":{"type":["string","null"],"format":"date-time"},"days_left":{"type":"integer"},"updated_at":{"type":["string","null"],"format":"date-time"},"first_domain_free":{"type":"boolean","description":"The first domain free rule covers this workspace (brand new: no subscription and no trial yet, enforcement on). `restricted` is the billing state; a workspace can be `restricted` and still connect its free domain, which is what `can_connect_now` answers."},"free_domains":{"type":"integer","description":"How many domains the workspace may connect before it has a subscription (one, unless set by `set-free-domains`); 0 when the rule does not cover it."},"free_domains_used":{"type":"integer","description":"How many it has open now (pending, propagating or live); counted only when the rule covers it."},"can_connect_now":{"type":"boolean","description":"Billing lets the workspace connect another domain now: the answer the connection gate gives, not a reading of `status`. The plan quota is separate (see `usage`)."}}},"AdminBillingTenantDetail":{"allOf":[{"$ref":"#/components/schemas/AdminBillingTenant"},{"type":"object","properties":{"invoices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"amount_due_cents":{"type":"integer"},"amount_paid_cents":{"type":"integer"},"currency":{"type":"string"},"created_at":{"type":["string","null"],"format":"date-time"},"hosted_invoice_url":{"type":["string","null"]}}}},"invoices_error":{"type":"string"},"events":{"type":"array","description":"The billing audit trail, newest first.","items":{"type":"object","properties":{"at":{"type":["string","null"],"format":"date-time"},"kind":{"type":"string","examples":["grace.started","comp.granted","subscription.active"]},"actor":{"type":"string","examples":["ops@example.com","owner dashboard","stripe:webhook","system:sweeper"]},"detail":{"type":"object"}}}},"notices":{"type":"array","description":"The billing email log, newest first.","items":{"type":"object","properties":{"kind":{"type":"string"},"key":{"type":"string"},"status":{"type":"string","enum":["pending","sent","failed","skipped"]},"attempts":{"type":"integer"},"error":{"type":["string","null"]},"created_at":{"type":["string","null"],"format":"date-time"},"sent_at":{"type":["string","null"],"format":"date-time"}}}},"previous_status":{"$ref":"#/components/schemas/BillingState"}}}]},"PromoCode":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"coupon":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"percent_off":{"type":["number","null"]},"amount_off_cents":{"type":["integer","null"]},"currency":{"type":["string","null"]},"duration":{"type":"string","enum":["once","repeating","forever"]},"duration_in_months":{"type":["integer","null"]},"valid":{"type":"boolean"}}},"max_redemptions":{"type":["integer","null"]},"times_redeemed":{"type":"integer"},"expires_at":{"type":["string","null"],"format":"date-time"},"first_time_transaction":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"created_here":{"type":"boolean","description":"Created from the owner dashboard (as opposed to elsewhere on the shared Stripe account)."}}},"SetupType":{"type":"string","description":"How a connection reaches live.","enum":["automatic","manual","async","mcp"]},"ConnectionStatus":{"type":"string","enum":["pending","propagating","live","failed"]},"Tenant":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"Application":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"tenant_id":{"type":"string"},"name":{"type":"string"},"environment":{"$ref":"#/components/schemas/Environment"},"default_origin":{"type":"string"},"connect_target":{"$ref":"#/components/schemas/ConnectTarget"},"sandbox":{"type":"boolean","description":"`true` for a **test mode** application, made with `\"sandbox\": true` on `POST /applications`. It runs the whole connect flow end to end (the widget, the API, webhooks) against simulated DNS, on reserved `.test` names only, and never touches a real domain, the free domain, the quota or billing. Fixed when the application is created. Omitted (treated as `false`) on a live application."},"nameserver_migration":{"$ref":"#/components/schemas/NameserverMigrationSetting"},"end_user_saved_access":{"type":"boolean","default":true,"description":"A returning end user may reuse the access their own secure sign-in kept, for their next domain in this application, after one tap of consent. On by default; set it with `PATCH /applications/{id}`. The access is that end user's own: bound to them and to this application, never usable by your team or by another end user. Always `false` for a test mode application, whose sign-ins are simulated and keep nothing."},"secure_sign_in":{"$ref":"#/components/schemas/SecureSignInStatus"},"created_at":{"type":"string","format":"date-time"}}},"SecureSignInStatus":{"type":"object","required":["available"],"description":"Whether the secure sign-in (the widget's cloud browser way to connect) can run for this application's workspace at all, for any provider. Read only: it follows how this deployment is set up, not a setting of the application. Whether it runs for one domain is the `cloud_browser` entry of that domain's `rails`.","properties":{"available":{"type":"boolean"},"reason":{"type":"string","enum":["switched_off","not_enabled_for_workspace"],"description":"Present when `available` is `false`. `switched_off`: this deployment has the secure sign-in off. `not_enabled_for_workspace`: it is on for a pilot list of workspaces, and this one is not on it."}}},"ConnectionRouting":{"type":"object","required":["mode","set_at"],"properties":{"mode":{"type":"string","enum":["edge","custom"],"description":"`edge`: records point at the CustomDomain™ edge. `custom`: at your own infrastructure."},"cname_target":{"type":"string","description":"For `custom`: the hostname subdomains and ALIAS-capable roots point at."},"apex_ipv4":{"type":"array","items":{"type":"string"},"description":"For `custom`: the addresses roots get on DNS providers with no ALIAS-style record."},"set_at":{"type":"string","format":"date-time","description":"When this routing was recorded for the domain."}}},"ConnectTarget":{"type":"object","required":["cname_target"],"properties":{"cname_target":{"type":"string"},"apex_ipv4":{"type":"array","items":{"type":"string"}}}},"ConnectTargetView":{"type":"object","required":["application_id","mode","edge"],"properties":{"application_id":{"type":"string"},"mode":{"type":"string","enum":["edge","custom"]},"connect_target":{"oneOf":[{"$ref":"#/components/schemas/ConnectTarget"},{"type":"null"}]},"edge":{"type":"object","properties":{"cname_target":{"type":"string"},"apex_ipv4":{"type":"array","items":{"type":"string"}}}},"warnings":{"type":"array","items":{"type":"string"},"description":"Advisory notes on a target just saved (PUT only): that `cname_target` does not resolve yet, or that with no `apex_ipv4` root domains at providers with no ALIAS-style record cannot connect."},"existing_domains":{"type":"object","required":["moved","kept"],"description":"What a PUT did to the application's existing domains (PUT only). Domains still waiting for DNS that were already on the new routing count as kept.","properties":{"moved":{"type":"integer","description":"Domains still waiting for DNS that took the new routing."},"kept":{"type":"integer","description":"Every other domain, left pointing where it does: connected domains, domains whose records were supplied or written, and domains still waiting for DNS that were already on the new routing."}}}}},"ConnectionDiagnosis":{"type":"object","required":["connection_id","domain","zone","status","all_found","records","issues"],"properties":{"connection_id":{"type":"string"},"domain":{"type":"string"},"zone":{"type":"string","description":"The DNS zone a panel manages (the registrable domain)."},"provider":{"type":"string"},"status":{"$ref":"#/components/schemas/ConnectionStatus"},"checked_at":{"type":"string","format":"date-time"},"all_found":{"type":"boolean"},"found_count":{"type":"integer"},"total":{"type":"integer"},"next_check_seconds":{"type":"integer"},"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"host":{"type":"string"},"name":{"type":"string","description":"What to type in the Name/Host field (\"@\" for the root)."},"value":{"type":"string"},"ttl":{"type":"integer"},"priority":{"type":"integer"},"status":{"type":"string","enum":["found","missing","mismatch","unverifiable"]},"observed":{"type":"array","items":{"type":"string"}},"observed_label":{"type":"string"},"at_provider":{"type":"boolean"}}}},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["doubled_host","cloudflare_proxied","aaaa_conflict","extra_a_records","conflicting_record","caa_blocks"]},"severity":{"type":"string","enum":["blocking","warning"]},"name":{"type":"string"},"host":{"type":"string"},"observed":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}}}}}},"SecureSignInSpan":{"type":"object","required":["samples","median_seconds","p90_seconds"],"properties":{"samples":{"type":"integer"},"median_seconds":{"type":"number"},"p90_seconds":{"type":"number"}}},"SecureSignInFlowView":{"type":"object","required":["provider","sessions","done","done_by_hand","in_progress","stopped","completion_rate","funnel","times","total","stops"],"properties":{"provider":{"type":"string","description":"Empty for every provider."},"sessions":{"type":"integer"},"done":{"type":"integer"},"done_by_hand":{"type":"integer"},"in_progress":{"type":"integer"},"stopped":{"type":"integer"},"completion_rate":{"type":"number","description":"Done and done by hand over started."},"funnel":{"type":"array","items":{"type":"object","required":["key","sessions","drop","drop_rate","of_started"],"properties":{"key":{"type":"string","enum":["started","sign_in_shown","signed_in","plan_ready","making_changes","done"]},"sessions":{"type":"integer"},"drop":{"type":"integer","description":"Sessions the stage before had that this one did not."},"drop_rate":{"type":"number"},"of_started":{"type":"number"}}}},"times":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/SecureSignInSpan"},{"type":"object","required":["key"],"properties":{"key":{"type":"string","enum":["sign_in_shown","signed_in","plan_ready","making_changes","done"]}}}]}},"total":{"$ref":"#/components/schemas/SecureSignInSpan"},"stops":{"type":"array","items":{"type":"object","required":["key","sessions","share"],"properties":{"key":{"type":"string","enum":["browser_not_started","left_at_sign_in","code_never_entered","provider_page_not_understood","provider_refused","timed_out","cancelled","changes_failed","error"]},"sessions":{"type":"integer"},"share":{"type":"number","description":"Of the sessions that stopped."}}}}}},"SecureSignInFlow":{"type":"object","required":["window","truncated","overall","providers"],"properties":{"window":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"days":{"type":"integer"},"application_id":{"type":"string"}}},"truncated":{"type":"boolean"},"overall":{"$ref":"#/components/schemas/SecureSignInFlowView"},"providers":{"type":"array","items":{"$ref":"#/components/schemas/SecureSignInFlowView"}}}},"SecureSignInSession":{"type":"object","required":["id","provider","connection_id","started_at","outcome","reached","total_seconds"],"properties":{"id":{"type":"string"},"provider":{"type":"string"},"connection_id":{"type":"string"},"started_at":{"type":"string","format":"date-time"},"outcome":{"type":"string","enum":["done","done_by_hand","running","stopped"]},"reached":{"type":"string","enum":["started","sign_in_shown","signed_in","plan_ready","making_changes","done"]},"stop":{"type":"string","description":"The plain reason, for a stopped session."},"last_step":{"type":"string"},"total_seconds":{"type":["number","null"]},"ended_at":{"type":"string","format":"date-time"}}},"SecureSignInTimeline":{"allOf":[{"$ref":"#/components/schemas/SecureSignInSession"},{"type":"object","required":["events"],"properties":{"failure":{"type":"string","description":"The failure the session ended in, a word from a fixed list."},"events":{"type":"array","items":{"type":"object","required":["step","seconds_since_start"],"properties":{"step":{"type":"string"},"seconds_since_start":{"type":"number"},"failure":{"type":"string"},"detail":{"type":"string"}}}}}}]},"ConnectAnalytics":{"type":"object","required":["window","widget","connections","daily","truncated"],"properties":{"window":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"days":{"type":"integer"},"application_id":{"type":"string"}}},"widget":{"type":"object","properties":{"sessions":{"type":"integer"},"entered_domain":{"type":"integer"},"analyzed":{"type":"integer"},"offered_automatic":{"type":"integer"},"shown_manual":{"type":"integer"},"succeeded":{"type":"integer"},"succeeded_automatic":{"type":"integer"},"errored":{"type":"integer"},"conversion_rate":{"type":"number"},"median_seconds_to_success":{"type":"integer"},"drop_off":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsCount"}},"errors":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsCount"}},"providers":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"sessions":{"type":"integer"},"succeeded":{"type":"integer"},"automatic":{"type":"integer"}}}},"domain_kinds":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"sessions":{"type":"integer"},"succeeded":{"type":"integer"}}}}}},"connections":{"type":"object","properties":{"total":{"type":"integer"},"live":{"type":"integer"},"pending":{"type":"integer"},"propagating":{"type":"integer"},"failed":{"type":"integer"},"live_rate":{"type":"number"},"median_seconds_to_live":{"type":"integer"},"by_provider":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"total":{"type":"integer"},"live":{"type":"integer"},"pending":{"type":"integer"},"failed":{"type":"integer"},"top_stuck":{"type":"string","description":"The most common reason this provider's not-live domains are stuck (a key of stuck). Absent when none are."},"top_stuck_count":{"type":"integer"},"median_seconds_to_live":{"type":"integer","description":"Median over this provider's live domains; 0 when none."}}}},"by_method":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsGroup"}},"by_kind":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsGroup"}},"stuck":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsCount"}},"time_to_live":{"type":"array","description":"Domains that went live by how long they took from being added: under_5m, 5m_to_1h, 1h_to_1d, over_1d, always all four in that order.","items":{"$ref":"#/components/schemas/AnalyticsCount"}}}},"daily":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"sessions":{"type":"integer"},"succeeded":{"type":"integer"},"created":{"type":"integer"},"went_live":{"type":"integer"}}}},"audience":{"type":"object","description":"Who opened the widget, from the session each widget open records (sessions from before this was recorded have none). Each list counts sessions, how many reached a finish screen (`succeeded`) and how many of their domains are live (`went_live`). Countries, browsers and systems list the eight busiest, then `other`; `unknown` is last.","properties":{"sessions":{"type":"integer"},"devices":{"type":"array","items":{"$ref":"#/components/schemas/AudienceRow"},"description":"desktop, mobile, tablet, bot or unknown."},"countries":{"type":"array","items":{"$ref":"#/components/schemas/AudienceRow"},"description":"ISO 3166-1 alpha-2 codes."},"browsers":{"type":"array","items":{"$ref":"#/components/schemas/AudienceRow"}},"systems":{"type":"array","items":{"$ref":"#/components/schemas/AudienceRow"}},"embeds":{"type":"array","items":{"$ref":"#/components/schemas/AudienceRow"},"description":"embedded, modal or unknown."}}},"install":{"type":"object","description":"Whether the widget has been seen in the builder's own product, per application, from the session each widget open records. A session is a console test when its token's end user is `console:` (the console's Try it live and welcome domain step); every other session is the product's. The console's design preview opens no session. Counts are sessions. `application_id` narrows it like the rest; an application with no session is not listed.","required":["applications"],"properties":{"applications":{"type":"array","items":{"type":"object","properties":{"application_id":{"type":"string"},"product_sessions":{"type":"integer","description":"Every session of the product ever recorded."},"test_sessions":{"type":"integer","description":"Every console test session ever recorded."},"window_product_sessions":{"type":"integer","description":"The product sessions that started inside the window."},"window_test_sessions":{"type":"integer","description":"The console test sessions that started inside the window."},"last_product_at":{"type":["string","null"],"format":"date-time","description":"When a product session last had an event; null when none ever did."},"last_product_host":{"type":"string","description":"The page origin (scheme, host, port, never a path) the newest product session reported; empty when it reported none."},"last_test_at":{"type":["string","null"],"format":"date-time"}}}}}},"secure_sign_in":{"type":"object","description":"The cloud browser sessions started in the window. `failures` is keyed by the failure taxonomy (bot_wall, captcha, region_blocked, vendor_error, user_cancel and the rest); `proxy_sensitive` marks the four a proxy in the customer's country could change. `proxy` has one row for the sessions without a vendor proxy and one for those with one, when there were any.","properties":{"sessions":{"type":"integer"},"signed_in":{"type":"integer"},"done":{"type":"integer"},"done_manual":{"type":"integer"},"sign_in_rate":{"type":"number"},"average_seconds_to_sign_in":{"type":"integer"},"average_seconds_to_done":{"type":"integer"},"providers":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"sessions":{"type":"integer"},"signed_in":{"type":"integer"},"planned":{"type":"integer"},"applied":{"type":"integer"},"done":{"type":"integer"},"done_manual":{"type":"integer"}}}},"failures":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"sessions":{"type":"integer"},"with_proxy":{"type":"integer"},"without_proxy":{"type":"integer"},"proxy_sensitive":{"type":"boolean"}}}},"proxy":{"type":"array","items":{"type":"object","properties":{"proxy":{"type":"boolean"},"sessions":{"type":"integer"},"signed_in":{"type":"integer"},"done":{"type":"integer"},"blocked":{"type":"integer","description":"Ended in bot_wall, captcha, region_blocked or vendor_error."},"sign_in_rate":{"type":"number"},"blocked_rate":{"type":"number"}}}}}},"truncated":{"type":"boolean"}}},"AudienceRow":{"type":"object","properties":{"key":{"type":"string"},"sessions":{"type":"integer"},"succeeded":{"type":"integer"},"went_live":{"type":"integer"}}},"AnalyticsCount":{"type":"object","properties":{"key":{"type":"string"},"count":{"type":"integer"}}},"AnalyticsGroup":{"type":"object","properties":{"key":{"type":"string"},"total":{"type":"integer"},"live":{"type":"integer"},"median_seconds_to_live":{"type":"integer","description":"Median over this group's live domains; 0 when none."}}},"TrafficStatusCounts":{"type":"object","description":"Requests by the status class of the answer the visitor got.","required":["1xx","2xx","3xx","4xx","5xx"],"properties":{"1xx":{"type":"integer","description":"Mostly 101 Switching Protocols (websockets)."},"2xx":{"type":"integer"},"3xx":{"type":"integer","description":"Includes the edge's own redirects (redirect_to and the www redirect)."},"4xx":{"type":"integer","description":"Includes 421 answered by the edge when the domain has no origin set."},"5xx":{"type":"integer","description":"Includes 502 answered by the edge when the origin could not be reached."}}},"TrafficLatency":{"type":"object","description":"The origin's time to first response byte, in milliseconds, over the requests that reached it.","required":["p50","p95","p99","mean","samples"],"properties":{"p50":{"type":"number"},"p95":{"type":"number"},"p99":{"type":"number","description":"Estimated from a fixed histogram; anything slower than 10 seconds reads as 10000."},"mean":{"type":"number"},"samples":{"type":"integer"}}},"TrafficRetention":{"type":"object","required":["hourly_days","daily_days"],"properties":{"hourly_days":{"type":"integer","description":"How long hourly figures are kept."},"daily_days":{"type":"integer","description":"How long daily figures are kept."}}},"ConnectionTraffic":{"type":"object","required":["connection_id","domain","range","granularity","from","to","serving","last_request_at","totals","series","retention"],"properties":{"connection_id":{"type":"string"},"domain":{"type":"string"},"range":{"type":"string","enum":["24h","7d","30d","90d"]},"granularity":{"type":"string","enum":["hour","day"]},"from":{"type":"string","format":"date-time","description":"Start of the first bucket."},"to":{"type":"string","format":"date-time","description":"End of the last bucket (exclusive); the last bucket is the current one."},"serving":{"type":"object","required":["through_edge","reason"],"properties":{"through_edge":{"type":"boolean","description":"Whether this domain's visitors reach the edge."},"reason":{"type":"string","enum":["live","verifying","not_live","dns_only"]}}},"last_request_at":{"type":["string","null"],"format":"date-time","description":"End of the last minute in which the edge served this domain; null when never (within retention)."},"totals":{"type":"object","required":["requests","status","bytes_out","error_rate","latency_ms","visitors"],"properties":{"requests":{"type":"integer"},"status":{"$ref":"#/components/schemas/TrafficStatusCounts"},"bytes_out":{"type":"integer","description":"Response body bytes sent to visitors: bodies relayed from the origin plus pages the edge wrote itself (redirects, the no-origin page). Not counted before 2026-11-02 for the edge-written pages."},"error_rate":{"type":"number","description":"Share of requests answered with a 5xx, 0 to 1."},"latency_ms":{"oneOf":[{"$ref":"#/components/schemas/TrafficLatency"},{"type":"null"}]},"visitors":{"type":"integer","description":"Approximate unique visitors; one seen on two UTC days counts once on each."}}},"series":{"type":"array","items":{"type":"object","required":["t","requests","status","bytes_out","error_rate","latency_ms","visitors"],"properties":{"t":{"type":"string","format":"date-time","description":"Bucket start."},"requests":{"type":"integer"},"status":{"$ref":"#/components/schemas/TrafficStatusCounts"},"bytes_out":{"type":"integer"},"error_rate":{"type":"number"},"latency_ms":{"oneOf":[{"$ref":"#/components/schemas/TrafficLatency"},{"type":"null"}]},"visitors":{"type":"integer"}}}},"retention":{"$ref":"#/components/schemas/TrafficRetention"}}},"TrafficSummary":{"type":"object","required":["application_id","range","granularity","from","to","totals","series","top_domains","retention"],"properties":{"application_id":{"type":"string","description":"The application the summary is narrowed to; empty for the whole workspace."},"range":{"type":"string","enum":["24h","7d","30d","90d"]},"granularity":{"type":"string","enum":["hour","day"]},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"totals":{"type":"object","required":["requests","status","bytes_out","error_rate","domains_with_traffic"],"properties":{"requests":{"type":"integer"},"status":{"$ref":"#/components/schemas/TrafficStatusCounts"},"bytes_out":{"type":"integer"},"error_rate":{"type":"number"},"domains_with_traffic":{"type":"integer","description":"How many domains the edge served at least once in the range."}}},"series":{"type":"array","items":{"type":"object","required":["t","requests","status","bytes_out","error_rate"],"properties":{"t":{"type":"string","format":"date-time"},"requests":{"type":"integer"},"status":{"$ref":"#/components/schemas/TrafficStatusCounts"},"bytes_out":{"type":"integer"},"error_rate":{"type":"number"}}}},"top_domains":{"type":"array","description":"The busiest domains, most requests first.","items":{"type":"object","required":["connection_id","domain","application_id","requests","status","bytes_out","error_rate","share","last_request_at"],"properties":{"connection_id":{"type":"string"},"domain":{"type":"string"},"application_id":{"type":"string"},"requests":{"type":"integer"},"status":{"$ref":"#/components/schemas/TrafficStatusCounts"},"bytes_out":{"type":"integer"},"error_rate":{"type":"number"},"share":{"type":"number","description":"This domain's part of the scope's requests, 0 to 1."},"last_request_at":{"type":["string","null"],"format":"date-time"}}}},"retention":{"$ref":"#/components/schemas/TrafficRetention"}}},"ApiKey":{"type":"object","required":["id","application_id","name","prefix","environment","is_default","created_at"],"properties":{"id":{"type":"string"},"application_id":{"type":"string","description":"The application the key belongs to."},"name":{"type":"string"},"prefix":{"type":"string","description":"The stored, non-secret prefix that identifies the key, for example cd_live_ab12cd34."},"environment":{"$ref":"#/components/schemas/Environment"},"scopes":{"type":"array","items":{"type":"string"}},"is_default":{"type":"boolean","description":"true on the workspace default key (at most one active per workspace)."},"last_used_at":{"type":"string","format":"date-time","description":"When the key last authenticated a request. Absent until it has been used."},"created_at":{"type":"string","format":"date-time"},"revoked_at":{"type":"string","format":"date-time","description":"When the key was revoked. Absent while the key is active."}}},"DefaultApiKey":{"type":"object","required":["key_id","prefix","created"],"properties":{"key_id":{"type":"string"},"prefix":{"type":"string","description":"The stored, non-secret prefix, for example cd_live_ab12cd34."},"created":{"type":"boolean","description":"true when this call minted the key; api_key is present only then."},"api_key":{"type":"string","description":"The full secret, cd_live_… or cd_test_…; shown once."}}},"Member":{"type":"object","required":["id","tenant_id","email","role","status","created_at"],"properties":{"id":{"type":"string"},"tenant_id":{"type":"string"},"email":{"type":"string"},"role":{"$ref":"#/components/schemas/Role"},"status":{"type":"string","enum":["active","pending","expired"],"description":"`active` once accepted, `pending` while the invite link works, `expired` once it has lapsed."},"invited_by":{"type":"string","description":"The accepting user's id in the calling application, when one was supplied at accept."},"inviter_email":{"type":"string","description":"Who sent (or last re-sent) the invite, resolved from the sending credential."},"inviter_name":{"type":"string","description":"The sender's display name, when one was supplied."},"invite_sent_at":{"type":"string","format":"date-time","description":"When the current invite link was issued."},"invite_expires_at":{"type":"string","format":"date-time","description":"When the current invite link stops working. Absent for members never invited by link."},"invite_token":{"type":"string","description":"The single-use invite token. Present only in the invite, resend and get-invite responses, never in the roster."},"accepted_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"InvitePreview":{"type":"object","required":["status","email","role","tenant_id","workspace_name"],"properties":{"status":{"type":"string","enum":["pending","accepted","expired","revoked","replaced"],"description":"`pending`: the link works. `accepted`: it was used. `expired`: it lapsed. `revoked`: an admin withdrew the invite. `replaced`: a newer invite was sent to the same address."},"email":{"type":"string","description":"The invited address."},"role":{"$ref":"#/components/schemas/Role"},"tenant_id":{"type":"string"},"workspace_name":{"type":"string","description":"The tenant's display name."},"inviter_name":{"type":"string"},"inviter_email":{"type":"string"},"invited_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time","description":"When the link stops (or stopped) working. Absent when it never expires."}}},"DnsRecord":{"type":"object","required":["type","host","value"],"properties":{"type":{"type":"string","examples":["CNAME","APEXCNAME","A","AAAA","TXT","MX"],"description":"DNS record type. `APEXCNAME` is the engine's provider-agnostic CNAME-at-the-apex type (a plain CNAME is illegal at a zone apex); it is realized to the host's native ALIAS / ANAME / flattened-CNAME on write, and shown to users as `ALIAS` in manual instructions."},"host":{"type":"string","description":"fully-qualified record name"},"value":{"type":"string"},"ttl":{"type":"integer","default":3600},"priority":{"type":["integer","null"],"description":"MX only"},"applied":{"type":"boolean","description":"true once written through a provider"},"change":{"type":"string","enum":["created","added","replaced","merged","existing"],"description":"What writing this record did to its name, recorded when we wrote it through a provider API. `created`: nothing of this type was there. `added`: our value joined a shared TXT or CAA set and the values already there were kept. `replaced`: the values of this type at the name were replaced (`prior` holds them). `merged`: an SPF policy was merged with the one already there (`prior` holds the original). `existing`: our exact value was already there, so removing the domain leaves it. Omitted when not recorded (a manual or one-click setup, or a record written before this was recorded)."},"prior":{"type":"array","description":"The values this record replaced, so removing the domain can put them back. Omitted when nothing was replaced or it is unknown.","items":{"$ref":"#/components/schemas/PriorValue"}},"prior_source":{"type":"string","enum":["provider","public_dns"],"description":"Where `prior` was read: `provider` (through the provider's API right before the write) or `public_dns` (observed in public DNS before the change). Omitted when unknown."}}},"PriorValue":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string"},"value":{"type":"string"},"ttl":{"type":"integer"},"priority":{"type":"integer"}}},"RemovalRecord":{"type":"object","required":["type","host","name","value","change","action"],"properties":{"type":{"type":"string","description":"The type as a DNS panel shows it (ALIAS, A, CNAME, TXT, MX, CAA)."},"host":{"type":"string","description":"fully-qualified record name"},"name":{"type":"string","description":"the name a DNS panel wants (\"@\", \"www\", \"_dmarc\")"},"value":{"type":"string"},"ttl":{"type":"integer"},"priority":{"type":"integer"},"change":{"type":"string","enum":["created","added","replaced","merged","existing","unknown"],"description":"What writing the record did to its name (see `DnsRecord.change`)."},"action":{"type":"string","enum":["delete","remove_value","restore","keep"],"description":"What a removal does with it: `delete` our value, take our value out of a shared TXT or CAA set (`remove_value`), put back what it replaced (`restore`), or `keep` it (another connected domain uses it, it was already there before we wrote it, or it is an SPF policy whose original we do not know)."},"prior":{"type":"array","items":{"$ref":"#/components/schemas/PriorValue"}},"prior_source":{"type":"string","enum":["provider","public_dns"]},"note":{"type":"string"}}},"RemovalPlan":{"type":"object","required":["connection_id","domain","connected_via","access","record_removal","default_choice","records_in_use_elsewhere","records","manual_steps","teardown"],"properties":{"connection_id":{"type":"string"},"domain":{"type":"string"},"provider":{"type":"string"},"provider_name":{"type":"string"},"connected_via":{"type":"string","description":"The rail that wrote the records (see `Connection.write_rail`), `manual` when none did, or `unknown_api` for an older connection written through a provider API."},"access":{"type":"string","enum":["kept","one_time","none"],"description":"What access we hold now."},"access_detail":{"type":"string"},"record_removal":{"type":"string","enum":["automatic","partial","reauthorize","manual","in_use","not_needed"],"description":"What choosing `remove` can do: `automatic` with the access we kept; `partial` (some automatically, the rest by hand: a Domain Connect revert cannot restore a replaced value, and the Route 53 access role cannot delete); `reauthorize` (one more sign-in or key, see `reauthorize`); `manual` (only by hand, see `manual_steps`); `in_use` (another connection still serves the domain, so the records stay); `not_needed` (nothing was added)."},"default_choice":{"type":"string","enum":["remove","keep"],"description":"The choice to offer first: `remove` when it can run without the person (automatic or partial), `keep` otherwise. A `DELETE` without a records choice keeps its original behaviour instead (see `DELETE /connections/{id}`)."},"reauthorize":{"type":"object","properties":{"methods":{"type":"array","items":{"type":"string","enum":["sign_in","api_key"]}},"provider":{"type":"string"},"flow":{"type":"string"},"regions":{"type":"array","items":{"type":"string"}}}},"records_in_use_elsewhere":{"type":"boolean"},"records":{"type":"array","items":{"$ref":"#/components/schemas/RemovalRecord"}},"manual_steps":{"type":"array","items":{"type":"string"},"description":"The exact steps to remove the records by hand, in order."},"notes":{"type":"array","items":{"type":"string"}},"teardown":{"type":"array","items":{"type":"string"},"description":"What always happens, whatever the choice."},"removal_started_at":{"type":"string","format":"date-time","description":"Set while a removal of the domain is running."},"removed":{"type":"boolean","description":"True once the domain is removed: the connection is gone and `result` is what the removal did with its records."},"removed_at":{"type":"string","format":"date-time"},"result":{"$ref":"#/components/schemas/RemovalOutcome"}}},"RemovalOutcome":{"type":"object","required":["choice","outcome"],"properties":{"choice":{"type":"string","enum":["remove","keep"]},"outcome":{"type":"string","enum":["removed","partly_removed","kept","manual","in_use","not_needed","failed"]},"via":{"type":"string"},"removed":{"type":"array","items":{"$ref":"#/components/schemas/RemovalResult"}},"restored":{"type":"array","items":{"$ref":"#/components/schemas/RemovalResult"}},"left_in_place":{"type":"array","items":{"$ref":"#/components/schemas/RemovalResult"}},"failed":{"type":"array","items":{"$ref":"#/components/schemas/RemovalResult"}},"manual_steps":{"type":"array","items":{"type":"string"}}}},"RemovalResult":{"type":"object","required":["type","name","value"],"properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"},"note":{"type":"string"}}},"CertificateView":{"type":"object","required":["host","status","managed"],"properties":{"host":{"type":"string"},"status":{"type":"string","enum":["issued","renewing","failed","pending","revoked","not_reported"],"description":"`issued`: a valid certificate. `renewing`: renewing keeps failing while the current certificate still serves (`last_error` says why). `failed`: no valid certificate. `not_reported`: the edge has not reported one yet."},"issuer":{"type":"string","description":"The issuing CA certificate's name, for example R11 or E6 (Let's Encrypt)."},"issued_at":{"type":"string","format":"date-time"},"renewed_at":{"type":"string","format":"date-time"},"not_before":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"days_left":{"type":"integer"},"next_renewal_at":{"type":"string","format":"date-time","description":"When the edge starts renewing (about 30 days before expiry). Omitted while a failing renewal is being retried."},"last_error":{"type":"string"},"failing_since":{"type":"string","format":"date-time"},"failure_count":{"type":"integer"},"managed":{"type":"boolean"},"attention":{"type":"string","enum":["failed","renewal_failing","expired","expiring"]},"updated_at":{"type":"string","format":"date-time"}}},"DomainEvent":{"type":"object","required":["id","domain","kind","created_at"],"properties":{"id":{"type":"string"},"application_id":{"type":"string"},"connection_id":{"type":"string"},"domain":{"type":"string"},"kind":{"type":"string","description":"One of connection.created, connection.applied, connection.live, connection.failed, connection.records.updated, connection.reapply.failed, connection.records_outdated, connection.disconnected, records.removed, records.rewritten, certificate.issued, certificate.renewed, certificate.failed, certificate.expiring, certificate.removed, drift.found, drift.fixed, drift.fix_failed, drift.action_required, drift.restored, access.granted, access.revoked, access.needs_reconnect, nameservers.started, nameservers.dnssec_cleared, nameservers.changed, nameservers.active, nameservers.failed, nameservers.rolled_back, nameservers.drifted. A connection or certificate kind that is also a webhook event type is written with the webhook, so the timeline and an integrator see the same history."},"detail":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"}}},"AccountConnection":{"type":"object","properties":{"id":{"type":"string"},"application_id":{"type":"string"},"domain":{"type":"string"},"status":{"type":"string"}}},"ProviderAccount":{"type":"object","required":["id","kind","provider","provider_name","label","access","scope","domains","credential_held","status","connections","uses","can_manage","application_ids","made_by","enforced_by","created_at"],"properties":{"needs_you":{"type":"object","description":"Why the account needs the person; absent when nothing does. The list puts these accounts first.","required":["reason"],"properties":{"reason":{"type":"string","enum":["refused","expired","check_failed","expiring","one_time_window","no_domains"],"description":"`refused`: the provider refused the key; reconnect it or remove the account. `expired`: the key reached its end, or a one time window passed with the key unused. `check_failed`: the daily check of the key failed three times in a row without the provider refusing it (a timeout, a server error, a domain the key no longer reads); the key may still work, and `POST /provider-accounts/{id}:check` tries it now. `expiring`: a key made at a sign-in ends within 30 days (`until`). `one_time_window`: a one time key waits for its domains to be connected, until `until`. `no_domains`: a continuous key the workspace holds that no domain uses."},"until":{"type":"string","format":"date-time","description":"When the key ends (`expiring`) or the one time window closes (`one_time_window`)."}}},"health":{"type":"object","description":"What the last check of the key found. The lifecycle sweep reads each continuous account's key once a day, and `POST /provider-accounts/{id}:check` does it on request. Absent for a one time account and for one that holds no key. It names no one and no domain, so a delegated agent token reads it as a member does.","required":["state","failures"],"properties":{"state":{"type":"string","enum":["ok","failing","refused","unchecked"],"description":"`ok`: the last check worked. `failing`: the last check or more reached no verdict (the account joins `needs_you` as `check_failed` from the third in a row). `refused`: the provider refused the key. `unchecked`: no check has run yet."},"checked_at":{"type":"string","format":"date-time","description":"When the key was last read against its provider; absent until then."},"failures":{"type":"integer","minimum":0,"description":"How many checks in a row reached no verdict. The daily check backs off after each (1, 4, 12, 24, then 48 hours)."}}},"made_by":{"type":"object","description":"How the key was made and by whom.","required":["how"],"properties":{"how":{"type":"string","enum":["pasted","console_sign_in","widget_sign_in","oauth"],"description":"`pasted`: a person pasted the key. `console_sign_in`: made at a secure sign-in a member started in the console. `widget_sign_in`: made at your customer's own sign-in, in the widget or one your backend started for them through the API. `oauth`: a member signed in with the company (`POST /provider-accounts:oauth-start`)."},"by":{"type":"string","description":"A member's e-mail, `a customer` for a key your customer's sign-in made (never their id), an API key's name, or absent when it was not recorded. A delegated agent token's answer always leaves it out (an agent has no need to know which person made a key); `how` stays."}}},"enforced_by":{"type":"string","enum":["provider","customdomain"],"description":"Who holds the key to the account's scope. `provider`: the key itself reaches only the zones it was made for (a Cloudflare API token's zone resources, Porkbun's per domain API access, an IAM policy on Route 53). `customdomain`: the key reaches the whole account at the provider, and CustomDomain™ uses it only for the domains in the scope."},"more_domains":{"type":"array","items":{"type":"string"},"description":"The domains the key lists at the provider that the workspace has not connected, sorted: \"This account holds 11 more domains\". A domain counts as connected when the workspace has a connection for it or for a name under it, in any application; a failed connection and a test mode one count for nothing. Only on `GET /provider-accounts/{id}` and on the answer of a secure sign-in's keep (`POST /browser-sessions/{sid}:keep`), and only for whoever manages the account (`can_manage`; never a viewer): listing a key's domains is a use of the key. It lists domains outside the account's scope too, which a connect refuses until the scope covers them. Empty for a provider that cannot list the domains of a key. Absent for anyone else, on the list, for a key an end user's secure sign-in made, for an account with no usable key, and when the provider could not be asked."},"id":{"type":"string"},"kind":{"type":"string","enum":["api_key"]},"provider":{"type":"string"},"provider_name":{"type":"string"},"label":{"type":"string","description":"What the account is called. A key the agent made reads ` key for `. A delegated agent token reads ` key` for a key made for another application and shared with its own."},"access":{"type":"string","enum":["continuous","one_time"]},"scope":{"type":"string","enum":["all","selected"]},"domains":{"type":"array","description":"The selected zones (scope `selected`).","items":{"type":"string"}},"credential_held":{"type":"boolean","description":"Whether the key is still kept and usable (false for a one time account past its hour). The key itself is never returned."},"status":{"type":"string","enum":["active","used","expired","needs_reconnect"]},"last_error":{"type":"string","description":"The provider's own words about the last failure with the key (a refused key reads `The provider refused the saved key: ...`). A delegated agent token's answer always leaves it out, for every key, because the words can name another application's domain; `status` and `needs_you.reason` say the state."},"created_by":{"type":"string","description":"Who connected it: the API key's name (`member:` for a member's key) for a pasted key; for a key made at a secure sign-in, the member or the workspace key whose console call started it, `end_user:` or `widget:` for one the widget started, and `api:` for one an API key started without the console's signed call. Only a key a member made in the console serves the application's other domains. A delegated agent token's answer leaves it out, as it leaves out `made_by.by`."},"last_used_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time","description":"When a one time account's key is deleted at the latest."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"connections":{"type":"array","items":{"$ref":"#/components/schemas/AccountConnection"}},"uses":{"type":"array","description":"What the account's access is used for.","items":{"type":"string"}},"can_manage":{"type":"boolean","description":"Whether the caller may change the account's access, scope or domains, connect domains with it and replace its key: an admin, an owner, or the member who connected it."},"application_id":{"type":"string","description":"Set for an account bound to one application: a lasting API key the cloud browser's agent made for it. Its key serves that application's domains and those of the applications in `application_ids`; connecting any other application's domain with it is refused (`403`). A delegated agent token's answer leaves it out for a key made for another application and shared with its own."},"application_ids":{"type":"array","description":"The other applications of the workspace an admin shared the key with, besides `application_id`, sorted. Empty when it is shared with none, for a key bound to no application (it serves every one) and for an end user's key (never shared). Change it with `updateProviderAccount`. A delegated agent token's answer leaves it empty for every key: the ids name the workspace's other applications, and the agent needs only that the key serves its own, which `application_id` says.","items":{"type":"string"}},"origin":{"type":"string","enum":["browser_agent"],"description":"`browser_agent` for a key the agent made after the end user signed in; absent for a key a person pasted."},"agent_key":{"$ref":"#/components/schemas/AgentKey"},"owner_kind":{"type":"string","enum":["workspace","end_user"],"description":"Whose key it is. `workspace`: a key the workspace holds (pasted, or made at a secure sign in a member started in the console). `end_user`: a key an end user's own sign in made (in the widget, or started by an API key without the console's signed call); it acts only for that end user, in its application, and the workspace can narrow or remove it but never use, widen or list it."},"end_user_ref":{"type":"string","description":"The platform's id for that end user, when the sign in named one. Not shown to a viewer."},"account_ref":{"type":"string","description":"The provider account the key belongs to, as the provider names it (a customer number, a user name). Not shown to a viewer."}}},"ConnectionServices":{"type":"object","required":["connection_id","application_id","domain","status","access","services","active_count"],"properties":{"connection_id":{"type":"string"},"application_id":{"type":"string"},"domain":{"type":"string"},"status":{"type":"string"},"provider":{"type":"string"},"provider_name":{"type":"string"},"access":{"type":"object","required":["mode","detail","connected_via"],"properties":{"mode":{"type":"string","enum":["kept","one_time","none"],"description":"`kept`: CustomDomain™ holds continuous access (the zone it hosts, a kept sign-in or Domain Connect grant, a continuous provider account, the Route 53 access role). `one_time`: the records were written with access that was not kept. `none`: a person or the provider wrote them."},"via":{"type":"string","enum":["managed_dns","sign_in","domain_connect","provider_account","route53_role"]},"detail":{"type":"string"},"connected_via":{"type":"string","description":"The rail that wrote the records."}}},"services":{"type":"array","items":{"type":"object","required":["id","name","active","state","detail"],"properties":{"id":{"type":"string","enum":["dns_connect","managed_dns","edge","tls","power","monitoring","auto_repair","redirects","email_records","caa"]},"name":{"type":"string"},"active":{"type":"boolean"},"state":{"type":"string","enum":["active","pending","attention","paused","inactive"]},"detail":{"type":"string"},"since":{"type":"string","format":"date-time"}}}},"active_count":{"type":"integer"}}},"DriftRecord":{"type":"object","required":["subdomain","type","verdict","expected"],"properties":{"subdomain":{"type":"string","description":"The record's name relative to the domain (\"@\" for the domain itself)."},"type":{"type":"string"},"verdict":{"type":"string","enum":["record_missing","record_changed"]},"expected":{"type":"array","items":{"type":"string"}},"observed":{"type":"array","items":{"type":"string"}}}},"MonitorView":{"type":"object","required":["connection_id","domain","watched","active","every","last_checked_at","result","drift","checked","repair","alerts"],"properties":{"connection_id":{"type":"string"},"domain":{"type":"string"},"watched":{"type":"boolean"},"active":{"type":"boolean"},"every":{"type":"string","description":"How often the domain is checked (hour)."},"last_checked_at":{"type":["string","null"],"format":"date-time"},"next_check_at":{"type":"string","format":"date-time"},"result":{"type":"string","enum":["ok","drift","inconclusive","unconfirmed","not_checked","not_watched"],"description":"The last check. `drift` is only reported after a second, independent look at the zone's own nameservers confirmed it; `inconclusive` means the lookup did not answer and the previous finding stands; `unconfirmed` means the first lookup saw a change the zone's own nameservers could not be asked to confirm (see `reason`): earlier drift stands and nothing is restored."},"reason":{"type":"string","enum":["ns_lookup_failed","timeout","all_servers_refused","no_server_answered","delegated","unsupported_type"],"description":"Set when `result` is `unconfirmed`, why the nameservers could not confirm."},"unconfirmed_checks":{"type":"integer","description":"Set when `result` is `unconfirmed`, how many checks in a row. At 3 the workspace gets one inbox entry."},"drift_since":{"type":"string","format":"date-time"},"drift":{"type":"array","items":{"$ref":"#/components/schemas/DriftRecord"}},"checked":{"type":"integer","description":"Records compared in the last check."},"error":{"type":"string"},"action":{"type":"object","description":"What was done about the drift: `auto_fixed` (put back), `fix_failed` (the repair failed, did not hold, or the records were put back 3 times in 24 hours and disappeared again) or `action_required` (left for the tenant).","properties":{"kind":{"type":"string","enum":["auto_fixed","fix_failed","action_required"]},"at":{"type":"string","format":"date-time"},"description":{"type":"string"}}},"attention":{"type":"string","enum":["action_required","fix_failed","drift"],"description":"Set while drift needs the tenant (action_required, fix_failed) or is being repaired (drift)."},"repair":{"type":"object","required":["automatic","detail"],"properties":{"automatic":{"type":"boolean","description":"True when CustomDomain™ holds continuous access and puts disappeared records back itself."},"paused":{"type":"boolean","description":"True when CustomDomain™ holds the access (`via`) but this deployment has automatic repair switched off (`MONITOR_AUTO_REPAIR`): missing records are reported, not put back. Omitted otherwise."},"via":{"type":"string","enum":["managed_dns","sign_in","domain_connect","provider_account"]},"detail":{"type":"string"}}},"alerts":{"type":"object","properties":{"webhooks":{"type":"boolean"},"email":{"type":"boolean"}}},"watching":{"type":"array","description":"The records the domain is held to.","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"}}}},"history":{"type":"array","items":{"$ref":"#/components/schemas/DomainEvent"}}}},"DisconnectResult":{"type":"object","required":["connection_id","domain","disconnected","records","serving","certificate","monitoring"],"properties":{"connection_id":{"type":"string"},"domain":{"type":"string"},"disconnected":{"type":"boolean"},"records":{"$ref":"#/components/schemas/RemovalOutcome"},"serving":{"type":"string","enum":["stopped"]},"certificate":{"type":"string","enum":["removed","kept","none"]},"monitoring":{"type":"string","enum":["stopped"]}}},"WritableRecord":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","examples":["CNAME","A","AAAA","TXT","MX","SPFM"]},"host":{"type":"string","description":"relative label, apex, or fully-qualified"},"value":{"type":"string"},"ttl":{"type":"integer","default":3600},"priority":{"type":"integer","description":"MX only"},"essential":{"type":"boolean","description":"fail the apply if this record cannot be written"}}},"Connection":{"type":"object","required":["id","application_id","domain","setup_type","status","created_at"],"properties":{"id":{"type":"string"},"application_id":{"type":"string"},"domain":{"type":"string"},"host":{"type":"string","description":"subdomain label; empty means the apex"},"provider_id":{"type":"string","description":"detected / applied DNS provider"},"setup_type":{"$ref":"#/components/schemas/SetupType"},"status":{"$ref":"#/components/schemas/ConnectionStatus"},"managed":{"type":"boolean","description":"`true` when the connection opted into **managed mode**: the control plane holds a durable, encrypted async grant and can re-apply (`POST /v1/connections/{id}:reapply`) or revert (`DELETE /v1/connections/{id}`) the template server-side without re-consent. Omitted (treated as `false`) for the default use-once connection."},"created_at":{"type":"string","format":"date-time"},"sandbox":{"type":"boolean","description":"`true` when the connection belongs to a test mode application. Its DNS is simulated, nothing real is read, written or served, and it counts for nothing (no free domain, quota, billing or metering). Copied from the application at create and never changed. Omitted (treated as `false`) on a real connection."},"last_checked_at":{"type":"string","format":"date-time","description":"When the propagation poller last examined this connection. Omitted until the first check."},"www_redirect":{"type":"boolean","description":"Serve an apex↔www redirect. Echoed from create."},"override_spf":{"type":"boolean","description":"Replace an existing SPF record instead of merging into it, where the provider supports it. Echoed from create."},"validate_dmarc":{"type":"boolean","description":"Stored and echoed from create; not acted on yet."},"validate_caa":{"type":"boolean","description":"Whether the Let's Encrypt CAA records are part of the desired record set. Echoed from create."},"monitor":{"type":"boolean","default":true,"description":"Whether the domain is enrolled in drift monitoring. Echoed from create, where it defaults to true when omitted, and honoured: the drift watch is registered when the connection goes live only if this is true. Connections created before the flag was honoured read true (they were monitored unconditionally, and were backfilled), so this is false only where a caller explicitly opted out."},"batch_id":{"type":"string","description":"The multi-domain session this connection was created in. Omitted for a standalone connect."},"end_user_ref":{"type":"string","description":"The integrator's own identifier for the end user who connected this domain. Set once at create and never changed: it binds widget tokens and saved access to the connection. Omitted for a console/direct connect, and from every answer a delegated agent token reads. The name of the client a domain is for is `client_label`."},"client_label":{"type":"string","maxLength":200,"description":"The name of the client or customer the domain is for, set at create or with `PATCH /connections/{id}`. Omitted when none is set. It is the platform's own note about the client: it is left out of every answer an end user's widget token or a delegated agent token reads, and an API key or an `app`-scoped token reads it."},"retried_at":{"type":"string","format":"date-time","description":"When a human (or the create-path resume, or real edge traffic) last asked for this connection to be re-verified. The retry clock is max(created_at, retried_at): a revived connection gets a fresh window from here, not from its original creation. Absent when it was never retried."},"routing":{"allOf":[{"$ref":"#/components/schemas/ConnectionRouting"}],"description":"Where this domain points: its application's routing when the connection was created. A change to the application's routing moves it only while it is still waiting for DNS; once connected it keeps this until `POST /v1/connections/{id}:retarget` moves it. Omitted only for a connection created before this was recorded, which follows its application's current routing."},"records_source":{"type":"string","enum":["integrator"],"description":"Present as `integrator` when the connection's desired record set was supplied through `PUT /v1/connections/{id}/records` rather than authored by us. Omitted for the usual server-synthesized or Domain Connect template-materialized set. Such a connection cannot use the Domain Connect rail, which applies our published templates at the provider."},"created_via":{"type":"string","enum":["","widget","console","api","agent","mcp"],"description":"Where the connection was created, recorded once at create and never changed. `widget`: an end user's connect-scoped widget token (the embedded widget in your product). `console`: the CustomDomain™ console. `api`: an API key, or an app-scoped token, from your server. `agent`: a delegated agent access token. `mcp`: the MCP server. Empty for connections created before this was recorded. A trusted server-side caller may name its surface with the `X-CustomDomain-Client` request header (`console` or `mcp`); the header is a label only and grants nothing."},"secure_root_domain":{"type":"boolean","description":"The edge also issues/secures the registrable apex alongside this subdomain connection. Omitted (treated as `false`) when unset."},"redirect_to":{"type":"string","format":"uri","description":"URL the edge 301s this host to (Power redirect target). Omitted when the connection is not a redirect."},"power_root_path_access":{"type":"array","items":{"type":"string"},"description":"URL paths the edge may static-serve at the root (Power root-path access). Omitted when none are configured."},"error_code":{"type":"string","description":"The last failure reason recorded for this connection, from whichever path failed, not only the background poller. It is persisted by: the propagation poller / `:recheck` verification (e.g. `propagation_timeout`, `setup_incomplete`, `pending_expired`, `domain_already_connected`); the foreground apply on `POST /connections/{id}/apply` (e.g. `dns_write_failed`, `ProviderAuthenticationError`, `spf_merge_failed`, `apex_not_supported`, `forwarding_not_supported`, `porkbun_api_access_disabled`); the OAuth callback (which also records `forwarding_not_supported`); and the Domain Connect async callback (both e.g. `provider_unavailable`, `ProviderAuthenticationError`, `apply_failed`, `internal_error`, or the provider's own `error` parameter). Rejected request validation (`400`) is deliberately NOT recorded here: a malformed request is not a connection failure. Omitted when healthy or never failed; cleared when the connection next verifies."},"error_message":{"type":"string","description":"Human-readable detail for `error_code`. Populated on the same paths and cleared alongside it. Omitted when there is none."},"write_rail":{"type":"string","enum":["api_key","sign_in","domain_connect","domain_connect_async","route53_role","provider_account","managed_dns"],"description":"The rail that last wrote this connection's records. Omitted when no rail wrote them (a manual setup, or a connection from before this was recorded). It decides what removing the domain can do with the records (`GET /connections/{id}/removal`)."},"provider_account_id":{"type":"string","description":"The connected provider account whose credential wrote this connection's records and, when the account's access is `continuous`, keeps them (repairs and removal). Omitted when none."},"removal_started_at":{"type":"string","format":"date-time","description":"Set while the domain is being removed: the records are being taken out and the connection is deleted when that finishes. The domain no longer serves from this moment. Omitted otherwise."},"dns_hosting":{"$ref":"#/components/schemas/ConnectionDnsHosting"}}},"ConnectionDnsHostingFilter":{"type":"string","enum":["hosted","moving","any"],"description":"`hosted`: served from a zone we run. `moving`: being set up or moved. `any`: hosted, moving or failed."},"ConnectionDnsHosting":{"type":"object","description":"Who runs the domain's DNS: a zone CustomDomain™ hosts, or a move to one. It is read from the managed DNS zone the connection is linked to and the workspace's nameserver moves, never from the connection itself, so it is on the list and on `GET /connections/{id}` and nowhere else a connection appears. A linked zone decides first (`active` is hosted, `awaiting_delegation` is moving, `failed` is failed). Without one, a nameserver move of the workspace on the domain or a parent of it decides (`active` is hosted, a move still under way is moving, one that failed because the domain's nameservers moved away again is failed; a rolled back or otherwise failed move counts for nothing). A test mode connection is always `none`.","required":["state"],"properties":{"state":{"type":"string","enum":["none","moving","hosted","failed"],"description":"`none`: nothing of ours runs this domain's DNS (no other field is set). `moving`: the zone is being set up or the nameservers are being moved, and the domain is not served from it yet. `hosted`: the nameservers point at the zone, which is what the world resolves. `failed`: the zone never became active, or the domain moved its nameservers away again; someone has to look."},"by":{"type":"string","enum":["customdomain","dns_host","custom"],"description":"Who runs the DNS: CustomDomain™'s own managed DNS (`customdomain`), our account at a DNS host we integrate with (`dns_host`; `provider` names it), or the platform's own list of nameservers (`custom`). Omitted when `state` is `none`."},"provider":{"type":"string","description":"The DNS host's provider id when `by` is `dns_host`, for example `cloudflare`."},"zone":{"type":"string","description":"The zone that is hosted or being set up: the connection's domain or a parent of it (`acme.com` for `shop.acme.com`)."},"since":{"type":"string","format":"date-time","description":"When the domain reached this state: the zone's activation for `hosted`, the start of the move for `moving`, the failure for `failed`."}}},"ConnectionReach":{"type":"object","description":"How CustomDomain™ reaches this domain's DNS to write records, from the access we keep (the order we use it: a zone we host, a kept sign-in or Domain Connect authorization, a connected account, the Route 53 role) and the domain's DNS hosting. A domain whose DNS is hosted is reached by the hosting, whoever runs the zone: an old sign-in or account at the previous DNS provider no longer writes anywhere that serves it.","required":["kind","can_reapply","managed_possible"],"properties":{"kind":{"type":"string","enum":["account","sign_in","domain_connect","dns_hosting","route53_role","none"],"description":"`account`: a provider account kept for the workspace (`account_id`, `label`, `provider`). `sign_in`: a kept sign-in at the DNS provider (`provider`). `domain_connect`: a kept one-click setup authorization at the DNS provider (`provider`). `dns_hosting`: the DNS is hosted by us (see `dns_hosting`). `route53_role`: the Route 53 access role, which may change records but not delete them. `none`: nothing is kept, so the next change needs a person at the DNS provider."},"account_id":{"type":"string","description":"The provider account (`GET /provider-accounts/{id}`) when `kind` is `account`."},"label":{"type":"string","description":"The account's label when `kind` is `account`. A delegated agent token reads ` key` for a key made for another application."},"provider":{"type":"string","description":"The DNS provider id the kept access is at."},"can_reapply":{"type":"boolean","description":"Whether `POST /connections/{id}:reapply` can write the domain's records now through this access. `false` for a zone not serving yet, a domain hosted at a DNS host we run, the Route 53 role and `none`."},"managed_possible":{"type":"boolean","description":"Whether this deployment can offer the Domain Connect sign-in that keeps access to the domain at its DNS provider: the one-click rail is configured with a client for the domain's provider, and the domain's records are ours (not a record set you supplied). It reads stored facts only; the provider's own answer comes when setup starts. When `false`, do not offer that upgrade."}}},"ConnectionUpdate":{"type":"object","description":"The settings of a domain `PATCH /connections/{id}` changes. Every field is optional and a field left out is unchanged; at least one is required. The body is decoded with unknown fields REJECTED, so the properties below are exactly the accepted set.","properties":{"client_label":{"type":"string","maxLength":200,"description":"The name of the client or customer the domain is for. Characters that draw nothing (a right to left override, a zero width space, the blank fillers, variation selectors, private use characters) are dropped, control characters and runs of white space become one space, and the name is trimmed. Only `\"\"` clears it: a value that is not empty but has nothing readable left (white space, or only invisible characters) is `400`, so it cannot take a name off. More than 200 characters is `400`."},"www_redirect":{"type":"boolean","description":"Send visitors of the root domain (`acme.com`) to `www.acme.com`. Root domains only: `true` on a subdomain is `422` `www_redirect_apex_only`. Available on every plan. Turning it on adds a `www` record to the records the domain needs; turning it off takes it out, and the edge then answers for `www.acme.com` only if you connected it as its own domain. Not for a test mode domain (`403` `sandbox_not_allowed`)."},"redirect_to":{"type":"string","maxLength":2048,"description":"$119"}}},"ConnectionUpdated":{"allOf":[{"$ref":"#/components/schemas/ConnectionWithRecords"},{"type":"object","required":["customer_action_required"],"properties":{"customer_action_required":{"type":"boolean","description":"`true` when the change adds a record that CustomDomain™ does not write: the domain's DNS is not ours and no kept access can write it (a kept account with `move_rewrite` on does), so the person adds the `www` record shown in `records` at their DNS provider, and `connection.records_outdated` was sent. `false` for every other change, a hosted zone's and a rewrite's included."}}}]},"ConnectionWithRecords":{"allOf":[{"$ref":"#/components/schemas/Connection"},{"type":"object","required":["records"],"properties":{"records":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecord"}},"end_user_email":{"type":"string","format":"email","description":"The end user's email address, when one was given and the feature is on. Present only on the response of the call that created the connection with it, and on `GET /connections/{id}` with an API key. Never in a list, a webhook, or any read by a widget token."},"ask_end_user_email":{"type":"boolean","description":"Present (true) on a create response only when the widget should offer the end user an optional email field: the feature is on, the caller is a widget token that may set one (not another end user's), the domain is not a test domain and the connection has no address yet. The widget then calls `PUT /connections/{id}/end-user-email`. Omitted otherwise."},"credential":{"$ref":"#/components/schemas/ConnectionCredential"},"reach":{"$ref":"#/components/schemas/ConnectionReach"}}}]},"ConnectionCredential":{"type":"object","description":"The lasting API key the cloud browser's agent made at the domain's DNS provider for this connection, on `GET /connections/{id}` only: its record, never the key. Omitted when the connection has none.","required":["account_id","provider","status","scopes","rights"],"properties":{"account_id":{"type":"string","description":"The provider account that holds the key (`GET /provider-accounts/{id}`)."},"provider":{"type":"string"},"status":{"type":"string","enum":["active","expiring","needs_reconnect","expired"],"description":"`active`: the key works. `expiring`: it works and ends within 30 days; the end user was asked to reconnect. `needs_reconnect`: the provider stopped accepting it. `expired`: it reached its end and was deleted; the domain stays connected and monitored, and repairs wait for a reconnect."},"name":{"type":"string","description":"The name the key was made with. A delegated agent token's answer leaves it out for every key."},"scopes":{"type":"array","items":{"type":"string"}},"account":{"type":"string","description":"The provider account's identifier when the page showed one (a customer number or user name). A delegated agent token's answer leaves it out for every key."},"session_id":{"type":"string","description":"The cloud browser session that made the key. A delegated agent token's answer leaves it out for every key."},"verified_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"notice":{"type":"string","enum":["d30","d7","expired"]},"reconnect_reason":{"type":"string","enum":["expiring","expired","refused"]},"reconnect_sent_at":{"type":"string","format":"date-time"},"renewed_at":{"type":"string","format":"date-time"},"old_key":{"type":"string","enum":["revoke_by_hand"]},"revoke_url":{"type":"string","format":"uri"},"rights":{"type":"array","items":{"type":"string","enum":["transfer","billing","account"]},"description":"What the key can do beyond the domain's DNS records, so the platform knows what it holds: `transfer` (it can transfer the domain away), `billing` (it can make charges on the account: Spaceship's renewals and purchases), `account` (a key with no scopes, which holds every right the provider's API gives the account, transfers and renewals included where the API offers them). Empty for a key that reaches the DNS records only. The keys are made with every domain scope the provider offers (the owner's decision of 2026-10-20)."}}},"AgentKey":{"type":"object","description":"What is kept about a lasting API key the cloud browser's agent made at a provider after the end user signed in. Never the key.","required":["scopes","rights"],"properties":{"name":{"type":"string","description":"The name the key was made with: `CustomDomain` and the application's name. A delegated agent token's answer leaves it out for every key."},"scopes":{"type":"array","items":{"type":"string"},"description":"The scopes it was made with, as the provider names them; empty for a provider whose keys have none."},"account":{"type":"string","description":"The provider account's identifier when the page showed one (a customer number or user name). Never an email address. Absent for a viewer."},"session_id":{"type":"string","description":"The cloud browser session that made it. Absent for a viewer."},"verified_at":{"type":"string","format":"date-time","description":"When the read through the provider's API answered with it."},"expires_at":{"type":"string","format":"date-time","description":"Its own end at the provider; absent for no end date."},"notice":{"type":"string","enum":["d30","d7","expired"],"description":"The last expiry notice sent."},"reconnect_reason":{"type":"string","enum":["expiring","expired","refused"],"description":"Why the end user is asked to sign in again."},"reconnect_sent_at":{"type":"string","format":"date-time","description":"When a reconnect link was last emailed or copied."},"renewed_at":{"type":"string","format":"date-time","description":"When a reconnect last swapped in a new key."},"old_key":{"type":"string","enum":["revoke_by_hand"],"description":"`revoke_by_hand`: the key a reconnect replaced still lives at the provider; revoke it at `revoke_url`."},"revoke_url":{"type":"string","format":"uri","description":"The provider's page where the key is revoked."},"rights":{"type":"array","items":{"type":"string","enum":["transfer","billing","account"]},"description":"What the key can do beyond the domain's DNS records, so the platform knows what it holds: `transfer` (it can transfer the domain away), `billing` (it can make charges on the account: Spaceship's renewals and purchases), `account` (a key with no scopes, which holds every right the provider's API gives the account, transfers and renewals included where the API offers them). Empty for a key that reaches the DNS records only. The keys are made with every domain scope the provider offers (the owner's decision of 2026-10-20)."}}},"RecheckResult":{"allOf":[{"$ref":"#/components/schemas/ConnectionWithRecords"},{"type":"object","description":"The body of `POST /connections/{id}:recheck`. Unlike `ReapplyResult` this IS a connection (the full `ConnectionWithRecords` shape, so it is a drop-in replacement for a `GET /connections/{id}` response) with the check's own findings attached.","required":["checked","records_resolved","retried","previous_status"],"properties":{"checked":{"type":"array","description":"Per-record verdict for the set that was resolved: the persisted records when the connection has any, otherwise (for a `pending` manual connection nobody wrote records for) the synthesized desired set.","items":{"allOf":[{"$ref":"#/components/schemas/DnsRecord"},{"type":"object","required":["resolved"],"properties":{"resolved":{"type":"boolean","description":"Public DNS answered with this record's expected value at check time."}}}]}},"records_resolved":{"type":"boolean","description":"True only when EVERY entry in `checked` resolved. An empty `checked` is `false`: nothing to verify is not \"everything verified\"."},"retried":{"type":"boolean","description":"True when this call re-entered a `failed` connection into verification (re-basing its timeout clock), rather than re-checking a connection that was already in flight."},"previous_status":{"type":"string","enum":["pending","propagating","live","failed"],"description":"The status the connection held when the request arrived."}}}]},"ReapplyResult":{"type":"object","description":"The receipt returned by `POST /connections/{id}:reapply`. It is deliberately NOT a `Connection`: the re-apply endpoint reports the outcome of the provider write and the record set that was written, and carries no other connection state.","required":["connection_id","reapplied","records"],"properties":{"connection_id":{"type":"string","description":"The connection the re-apply ran against (the `{id}` path parameter)."},"reapplied":{"type":"boolean","description":"Always `true` on a `200`: the provider accepted the write for every template in the grant's bundle. Failures are reported as `409` (not managed / grant revoked), `422` (a provider account's key or write refused), `503` (managed rail unavailable) or `500`, never as `reapplied: false`."},"via":{"type":"string","enum":["provider_account"],"description":"`provider_account` when a continuous provider account's key wrote the records; omitted for a kept grant or a zone CustomDomain™ hosts."},"records":{"type":"array","description":"The authoritative desired record set as recomputed and written: the materialized template records for a template bundle, the records CustomDomain™ wrote for a provider account, otherwise the connection's default desired set.","items":{"$ref":"#/components/schemas/DnsRecord"}}}},"Route53RoleStart":{"type":"object","description":"The answer of `POST /connections/{id}/route53-role:start`.","required":["connection_id","quick_create_url","template_url","region","stack_name","role_name","external_id","trusted_principal_arn","record_name","instructions"],"properties":{"connection_id":{"type":"string"},"quick_create_url":{"type":"string","format":"uri","description":"Opens the AWS CloudFormation console with the template and every parameter filled in. Open it in a new tab."},"template_url":{"type":"string","format":"uri","description":"The public S3 URL of the CloudFormation template."},"region":{"type":"string","description":"The AWS console region the link opens in. IAM roles are global, so it does not limit the role."},"stack_name":{"type":"string","description":"The stack name the link proposes."},"role_name":{"type":"string","description":"The role the stack creates: CustomDomainDNSAccess- followed by the external ID."},"external_id":{"type":"string","description":"The external ID the role requires, generated by CustomDomain™ once per connection. AWS does not treat it as a secret."},"trusted_principal_arn":{"type":"string","description":"The CustomDomain™ AWS principal the role trusts."},"record_name":{"type":"string","description":"The name the role may change, together with its www name and their verification names."},"hosted_zone_id":{"type":"string","description":"The hosted zone passed to this call, when one was."},"role_arn":{"type":"string","description":"The role already verified for this connection, when there is one."},"instructions":{"type":"array","items":{"type":"string"},"description":"Plain steps to show the customer."}}},"Route53RoleComplete":{"type":"object","description":"The answer of `POST /connections/{id}/route53-role:complete`.","required":["connection","records","role_arn","zone"],"properties":{"connection":{"$ref":"#/components/schemas/Connection"},"records":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecord"}},"role_arn":{"type":"string","description":"The verified role, now stored so an empty call re-applies with it."},"zone":{"type":"string","description":"The Route 53 hosted zone the records were written into."}}},"BrowserSessionEvent":{"type":"object","description":"One step of the cloud browser sign in window, reported by the popup.","required":["step"],"additionalProperties":false,"properties":{"step":{"type":"string","enum":["sheet_shown","sheet_accepted","sheet_declined","code_shown","code_sent","push_shown","social_card_shown","social_try_anyway","social_declined","social_refused","passkey_shown","overlay_shown","overlay_sent","handback_shown","fallback_manual","window_closed"]},"detail":{"type":"string","maxLength":64,"pattern":"^[A-Za-z0-9_.:-]{0,64}$","description":"One short word that goes with the step, never personal data, typed text or a URL."},"token":{"type":"string","description":"The session token, only when it cannot be sent as a header (a beacon)."}}},"BrowserSessionView":{"type":"object","required":["id","state","provider","domain"],"description":"One cloud browser session as the popup may see it. `live_view_url` and `live_view_origin` are present only in `awaiting_sign_in` and `manual_assist` (`interactive` true) and, read only, in `checking`, `plan_ready`, `applying` and `verifying`; never in a terminal state. The address is a bearer: anyone holding it can drive the browser. While the customer signs in it is the live view of the newest tab of the remote browser on the provider's hosts or a social sign in host of the provider (a sign in popup), and the first tab's again once that one closes. On Browserbase it is always that tab's own view, so the debugging socket its `wss` parameter names is that tab's too. On Kernel (`vendor` is `Kernel`) the live view is on a host of the session's own browser (`https://.kernel.sh:8443/browser/live/...`, which `live_view_origin` names) and shows the browser's active tab; the key relay's socket is then `relay_socket`.","properties":{"id":{"type":"string"},"state":{"type":"string","enum":["created","awaiting_sign_in","checking","plan_ready","applying","verifying","manual_assist","key_ready","done","done_manual","cancelled","expired","abandoned","failed"]},"provider":{"type":"string"},"provider_name":{"type":"string"},"vendor":{"type":"string","description":"The browser hosting company."},"domain":{"type":"string"},"site":{"type":"string","description":"The provider's registrable domain, for example namecheap.com. The popup shows it beside a lock while the customer signs in."},"interactive":{"type":"boolean","description":"True when the customer may type in the live view."},"live_view_url":{"type":"string","format":"uri"},"live_view_origin":{"type":"string","description":"The origin of `live_view_url`: the vendor's one pinned origin on Browserbase, the session browser's own host on Kernel."},"relay_socket":{"type":"string","description":"Only while the person is in control (`awaiting_sign_in`, a hand back, `manual_assist`) and only when the session's vendor lets the person's own browser type into the page through a socket of its own (`Kernel`): a browser level debugging socket, `wss://.kernel.sh:8443/browser/cdp?jwt=...`. A bearer like the live view; never in a terminal state. Absent on Browserbase, whose live view URL carries its own socket."},"relay_target":{"type":"string","description":"With `relay_socket`: the vendor's id of the tab the live view shows, for the key relay to attach to. Absent when it is not known yet; the popup then picks the first tab on the provider's site."},"deadline":{"type":"string","format":"date-time","description":"The next timer that matters: the sign in window in `awaiting_sign_in`, the approval window in `plan_ready`, the apply window in `applying`, the hard cap otherwise. A code prompt keeps the sign in window open for ten minutes from its first sight and raises the hard cap by five minutes, to twenty at most."},"plan":{"$ref":"#/components/schemas/BrowserPlan"},"manual":{"type":"object","description":"Present in `manual_assist`: the records the customer adds by hand.","properties":{"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"},"ttl":{"type":"integer"},"present":{"type":"boolean","description":"The live tick from public DNS, refreshed about every 8 seconds."}}}},"guide_url":{"type":"string"}}},"notice":{"type":"string","enum":["not_signed_in","switching_account"],"description":"`not_signed_in`: present after a `:signed-in` that landed on the sign in page, until the customer presses the button again. `switching_account`: after `:switch-account`, while the cloud browser signs out of the provider; `interactive` is false and there is no `form` or `signals` until the sign in is back."},"wrongAccount":{"type":"object","required":["tried","max"],"description":"In `awaiting_sign_in`: the account signed in does not hold the domain (the provider's DNS page said so twice, and its account switcher, where it has one, opened none that does). The customer chooses: `:switch-account` to sign in with another account, or `:cancel`. The live view stays (they may switch accounts by hand in it and press \"I'm signed in\" again, which counts no new try); there is no `form`. On a session that ended because the third account did not hold the domain either, the last count without `account`. Never the domain on other nameservers: that ends with `browser_not_provider_dns`.","properties":{"account":{"type":"string","maxLength":64,"description":"The name the provider shows for the account signed in (a user name, a customer number or an address, read from its header or account menu), shown to this customer only and never stored or logged; an address is masked to its first character and its domain (`j***@gmail.com`). Absent when the page shows none."},"tried":{"type":"integer","minimum":1,"maximum":3,"description":"How many accounts were found not to hold the domain."},"max":{"type":"integer","description":"How many may be tried: 3."}}},"left_key":{"type":"object","required":["name"],"description":"An API key the cloud browser made at the provider and CustomDomain did not keep (the provider's API refused it, it could not be stored, or the first write with it failed), so it is still live in the customer's account and most providers offer no API to delete it. Present from then on, in every state, so the popup can name it and link the provider's page to delete it. Never the key itself.","properties":{"name":{"type":"string","maxLength":80,"description":"The name the key was made with, \"CustomDomain Acme 2026-10-21\"."},"page":{"type":"string","format":"uri","description":"The provider's page that lists and deletes its keys, when known."}}},"kept_key":{"type":"object","required":["rights"],"description":"The lasting API key the cloud browser made at the provider and CustomDomain kept for the connection, once it is kept (the session has recorded `key_connected`). Present from then on, in every state, so the popup's last screen can name it: what to look for on the provider's key page and where to delete it later. Never the key itself. A key that was made and not kept is `left_key`, never this.","properties":{"name":{"type":"string","maxLength":80,"description":"The name the key was made with, \"CustomDomain Acme 2026-10-21 1528 3f9a\". Absent for a provider whose key is the account's own and has no name of its own (Namecheap)."},"page":{"type":"string","format":"uri","description":"The provider's page that lists and deletes its keys, when known."},"rights":{"type":"array","items":{"type":"string","enum":["transfer","billing","account"]},"description":"What the key can do beyond the domain's DNS records, as `rails.cloud_browser.key.rights`: empty for a key that reaches DNS only."},"expires_at":{"type":"string","format":"date-time","description":"When the key ends. Absent for a key with no end date."},"reused":{"type":"boolean","description":"`true` when no key was made in this session: the provider's key page still listed the row of the key an earlier sign in made for this same provider account (its name and account, as CustomDomain recorded them), and the key CustomDomain stored for it, checked again and still working, was used instead. No key was read off the page. `name` and `expires_at` are then that key's own. Absent for a key made in this session."}}},"api_activation":{"type":"object","required":["kind"],"description":"Present while the customer signs in (created, awaiting_sign_in) when the session will also turn the provider's API on for the account if it is off. `order`: it opens the provider's free order for it (IONOS's free API access, in its shop, never above zero), whose terms and order the customer accepts and places themselves in the live view (`handback.reason` `order`). `access`: it turns the account's API access on and allows CustomDomain's address (Namecheap), the terms and the password it asks for being the customer's. The popup says so under Sign in, with the provider's terms when known.","properties":{"kind":{"type":"string","enum":["order","access"]},"terms":{"type":"string","format":"uri","description":"The provider's terms for its API product, when known."}}},"key_replaces":{"type":"boolean","description":"`true` when the key this session makes is a password that replaces the provider's old one (REG.RU's alternative API password), so anything still using the old password stops working. The popup says so while the key is made, before the password is set."},"error":{"type":"object","description":"Present in `manual_assist` and `failed`, and in `checking` after the records changed under a plan. `browser_wrong_account` ends a session whose accounts did not hold the domain.","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"sign_in_viewport":{"$ref":"#/components/schemas/BrowserViewport"},"work_viewport":{"$ref":"#/components/schemas/BrowserViewport"},"sign_in_frame":{"type":"integer","minimum":1,"description":"In `awaiting_sign_in` only: the bottom edge of the provider's sign in card on the remote screen, in CSS pixels from the top and under `sign_in_viewport`'s height, measured when the sign in page opened. The popup ends its frame just under it, so the links below the card stay out of sight. Sent only while the sign in tab still shows the page it was measured on and no human check or second window is on screen; once that changes it is gone for the rest of the session. Absent means show the whole screen."},"signed_in_detected":{"type":"boolean","description":"In `awaiting_sign_in` only: the provider's sign in page gave way to its DNS panel page and the panel held across two polls, so the customer looks signed in. A hint: the popup then calls `:signed-in`, which checks the page itself. Absent means not detected."},"check":{"type":"boolean","description":"In `awaiting_sign_in` only: the vendor reports the sign in tab with the title of a known human check page (Cloudflare's \"Just a moment...\"), so the popup asks the customer to tick the box. Only this boolean is sent, never the title. A page can fake its title, so it is a hint for the popup's words and nothing else: it never counts toward `signed_in_detected`, and nothing clicks or types because of it. Absent means no check page."},"signals":{"$ref":"#/components/schemas/BrowserSignals"},"handback":{"$ref":"#/components/schemas/BrowserHandback"},"form":{"$ref":"#/components/schemas/BrowserSignInForm"},"password_again":{"$ref":"#/components/schemas/BrowserPasswordAgain"},"no_live_page":{"type":"boolean","description":"The popup never shows the provider's page (every session since 2026-11-02, Kernel's since 2026-10-30): the sign in, a code, a push, a link wait and the backup are the popup's own screens. The only real pages are a human check (`live_check`), a social provider's own sign in and the provider's terms, order or account details handed back (`handback` `agreement`, `order` or `account`). The relay still types for our form. Absent (false) from an older control plane, which keeps the old behaviour."},"live_check":{"type":"boolean","description":"With `no_live_page`: a human check (a CAPTCHA, a bot wall) is shown on the provider's real page, zoomed to it, because the person answers it there. Absent on Kernel, where the popup's own check screen comes first."},"idp":{"type":"object","required":["provider","domain","state"],"description":"In `awaiting_sign_in` on a `no_live_page` session: the identity provider step (`POST :idp`). While its `state` is `starting` or `form` the customer is in the vendor's form, not in the remote browser: `form`, `signals`, `signed_in_detected`, `check`, `interactive` and the relay are absent. `finishing`: the remote browser was made again on the signed in profile and is back on the provider's sign in page with a fresh `relay_socket` and `form`; the popup forwards the customer's press of the provider's own button. `failed`: `error_code` says why (the vendor's own codes such as `credentials_invalid`, `account_locked`, `unsupported_auth_method`, `captcha_blocked`, or the step's `vendor_error`, `expired`, `social_timeout`, `cancelled`); the customer tries again (`:idp`) or uses the password (`:idp-cancel`).","properties":{"provider":{"type":"string","enum":["google","apple"]},"domain":{"type":"string","description":"The identity provider's site, for example google.com."},"connection_id":{"type":"string","description":"The vendor's connection, opaque."},"handoff_code":{"type":"string","description":"Only while `state` is `form`: the vendor's single use bearer, which the popup exchanges in the customer's browser for a token of its own. Never logged or stored."},"state":{"type":"string","enum":["starting","form","finishing","failed"]},"error_code":{"type":"string","description":"With `failed`: a short machine word."}}}}},"BrowserSignals":{"type":"object","required":["host","hostVerified"],"description":"Present only while the customer is in control (in `awaiting_sign_in`, or while the page is handed back), and only while fresh: what the provider's page asks of the customer, so the popup can say it in its own words. It never holds a field's value. A hint for the popup's words and nothing else.","properties":{"host":{"type":"string","description":"The live page's host name; empty when its address is not https (a blank window)."},"hostVerified":{"type":"boolean","description":"The host is one of the provider's hosts or one of its social sign in hosts, on an https address."},"field":{"type":"object","required":["kind"],"description":"The focused editable field, if any.","properties":{"kind":{"type":"string","enum":["username","password","code","text"]},"label":{"type":"string","maxLength":60,"description":"What the page calls the field: its label, aria label or placeholder."},"maxLength":{"type":"integer","minimum":1,"maximum":256}}},"codePrompt":{"type":"object","required":["kind"],"description":"The page asks for a code.","properties":{"kind":{"type":"string","enum":["sms","app","email","unknown"]},"digits":{"type":"integer","minimum":4,"maximum":10}}},"push":{"type":"boolean","description":"The page waits for an approval on another device. Never set with `linkPrompt`."},"linkPrompt":{"type":"boolean","description":"The page says a sign in or approval link was sent (\"we sent you a link\", \"check your email to confirm\", \"approve this sign in\"), in English and in the providers' German, Spanish, French and Italian. The customer opens it in their mail and comes back; the popup may then click the form's `continue` control. Like a code prompt, it keeps the sign in open for 10 minutes from its first sight."},"social":{"type":"array","description":"The social sign in buttons the page shows.","items":{"type":"string","enum":["google","apple","facebook","amazon","microsoft","github"]}},"passkey":{"type":"boolean","description":"The page asks for a passkey or a security key."},"check":{"type":"boolean","description":"A CAPTCHA or a bot wall is showing."},"socialRefused":{"type":"string","enum":["google"],"description":"The identity provider whose own page says it will not sign this browser in (Google's \"Couldn't sign you in\"). The popup shows its own screen instead, offering the provider's password."},"formError":{"type":"string","maxLength":120,"description":"The error the provider's own page shows near its form (\"That password is incorrect\"): the text of an alert, a live region, the description of an invalid field or a common error element, from an element that holds no field. Every word with an at sign and every run of four or more digits is replaced with an ellipsis. Never on a social sign in host's page."},"focus":{"$ref":"#/components/schemas/BrowserRect"},"viewport":{"type":"object","required":["w","h"],"description":"The page's own viewport (the remote browser's), in CSS pixels.","properties":{"w":{"type":"integer"},"h":{"type":"integer"}}}}},"BrowserRect":{"type":"object","required":["x","y","w","h"],"description":"The region of the page that matters now, in CSS pixels from the top left of the page's viewport and clipped to it, for the popup to zoom to: the form around the focused field, else the main form, else the challenge's box on a check page, else the main card on a Google or Apple page.","properties":{"x":{"type":"integer"},"y":{"type":"integer"},"w":{"type":"integer"},"h":{"type":"integer"}}},"BrowserSignInForm":{"type":"object","required":["identifier","steps"],"description":"Present while the customer signs in, for a provider whose sign in form is known: the provider's form, so the popup's own form can drive it from the customer's browser over the vendor's debugging socket (the live view's `wss` parameter). No keystroke goes through CustomDomain™. Selectors are reviewed constants, not secrets; one that matches nothing on the day leaves the customer on the live page.","properties":{"identifier":{"type":"string","enum":["email","username","email_or_username","username_or_customer"],"description":"What the first field takes."},"steps":{"type":"array","description":"The form's pages in order (two for a provider that asks for the identifier first).","items":{"type":"object","required":["fields","submit"],"properties":{"fields":{"type":"array","items":{"type":"object","required":["kind","selector"],"properties":{"kind":{"type":"string","enum":["username","password"]},"selector":{"type":"string","description":"A CSS selector for document.querySelector."}}}},"submit":{"type":"string","description":"A CSS selector of the control that sends the step."}}}},"social":{"type":"object","description":"The provider's own social sign in buttons the session allows, by kind.","additionalProperties":{"type":"string"},"properties":{"google":{"type":"string"},"apple":{"type":"string"},"facebook":{"type":"string"},"amazon":{"type":"string"},"microsoft":{"type":"string"},"github":{"type":"string"}}},"passkeyAlt":{"type":"string","description":"The selector of the provider's \"use another way\" control on a passkey prompt."},"emailLink":{"type":"boolean","description":"The provider may email a sign in link instead of a code."},"keyTyped":{"type":"boolean","description":"The provider's page takes a value only from real key events (its submit stays disabled after a text insert), so the popup types each character as a key."},"continue":{"type":"string","description":"The selector of the page's own \"Continue\", \"I've confirmed\" or \"Done\" control on the page that waits for a code or a link, for the popup to click from the customer's browser when they come back from their email. Absent when it was not seen (today, every provider)."},"resend":{"type":"string","description":"The selector of the page's own \"Resend the code\" or \"Resend the link\" control. Absent when it was not seen (today, every provider)."},"forgotUrl":{"type":"string","format":"uri","description":"The provider's own \"forgot password\" page, https on the provider's own hosts, for the popup to open in a new tab of the customer's own browser (never in the cloud browser), so the reset email's link opens there too. Absent when it was not seen."},"consent":{"type":"string","description":"The accept button of the provider's cookie banner, for the popup to press from the customer's browser before a social button the banner can cover (the `idp` step's `finishing`); the agent presses the same one later. Absent for a provider with no banner on record."}}},"BrowserPasswordAgain":{"type":"object","required":["field"],"description":"Present after the sign in while the agent waits on the account password the provider asks for again (Infomaniak, before it shows a new API key), for a provider whose prompt was reviewed. The popup asks for the password on its own screen and types it into `field` from the customer's browser over `relay_socket`, as it does for the sign in form, then presses `submit` (Enter when it is absent). No keystroke goes through CustomDomain™ and the agent never sees the password. Absent otherwise: the customer answers on the provider's page.","properties":{"field":{"type":"string","description":"A CSS selector of the prompt's password field."},"submit":{"type":"string","description":"A CSS selector of the control that sends it; absent when Enter sends it."}}},"BrowserHandback":{"type":"object","required":["reason"],"description":"$11a","properties":{"reason":{"type":"string","enum":["code","check","agreement","order","account"]},"relay":{"type":"boolean","description":"With `reason: code` only: the provider asks for the code in a frame of its own (Squarespace's \"Verify to continue\") and the code is asked on the popup's own screen, with no live view taking input. The customer types it there and `POST :code` sends it; the agent types it into the provider's frame and presses its verify button. Absent (false) for a code the customer types in the live view."},"rejected":{"type":"boolean","description":"With `relay`: the provider refused the last code sent, so the screen says so and asks again."}}},"BrowserViewport":{"type":"object","required":["width","height"],"description":"The remote screen's size in CSS pixels, sent with the live view: `sign_in_viewport` while the customer signs in (the size the popup last asked for with `:viewport`, when it did), `work_viewport` after.","properties":{"width":{"type":"integer"},"height":{"type":"integer"}}},"BrowserPlan":{"type":"object","required":["hash","base_hash","changes","unchanged","approve_by"],"properties":{"hash":{"type":"string","description":"The sha256 of the plan, 64 hex characters. `:approve` sends all of it."},"base_hash":{"type":"string","description":"The hash of the page the plan was made from."},"changes":{"type":"array","description":"Removes, then changes, then adds. Values are shown in full.","items":{"type":"object","required":["op","type","name"],"properties":{"op":{"type":"string","enum":["add","replace","remove"]},"type":{"type":"string"},"name":{"type":"string","description":"The name as the provider's page shows it, `@` for the root."},"old":{"type":"string"},"new":{"type":"string"},"ttl":{"type":"integer","description":"The rounded value that will be written."},"priority":{"type":"integer"},"reason":{"type":"string","description":"Why a record that is not ours goes."}}}},"unchanged":{"type":"integer","description":"How many records on the page stay as they are."},"approve_by":{"type":"string","format":"date-time"}}},"AccountConnectResult":{"type":"object","description":"One domain's outcome of connecting with a kept key.","required":["domain","status"],"properties":{"domain":{"type":"string"},"application_id":{"type":"string","description":"The application the domain was connected into (`POST /provider-accounts/{id}/connect`)."},"connection_id":{"type":"string"},"status":{"type":"string","enum":["connected","already","failed"]},"message":{"type":"string"}}},"SavedAccess":{"type":"object","description":"A kept provider key that may act for a domain, for the caller. Never the key.","required":["account_id","provider","provider_name","label","how","owner_kind","scope","zone","ready","status"],"properties":{"account_id":{"type":"string"},"provider":{"type":"string"},"provider_name":{"type":"string"},"label":{"type":"string","description":"The account's label. A delegated agent token reads ` key` for a key made for another application and shared with its own, and an end user's token always reads ` key`."},"how":{"type":"string","enum":["api_key","secure_sign_in"],"description":"How the key came: a person pasted it, or the agent made it at a secure sign in."},"owner_kind":{"type":"string","enum":["workspace","end_user"]},"scope":{"type":"string","enum":["all","selected"]},"zone":{"type":"string","description":"The domain's zone at the provider."},"ready":{"type":"boolean","description":"True when the key's scope holds the zone. False: a read with the key showed it reaches the zone, and using it adds the zone to its scope."},"status":{"type":"string","enum":["active","needs_reconnect"],"description":"`needs_reconnect` for a key that still works until its end date."},"application_id":{"type":"string","description":"The application the key is bound to. A delegated agent token's answer leaves it out for a key made for another application, and an end user's token's answer for every key."},"key_name":{"type":"string","description":"The name an agent key was made with. A delegated agent token's and an end user's token's answers leave it out for every key."},"key_expires_at":{"type":"string","format":"date-time"},"last_used_at":{"type":"string","format":"date-time"},"from_domain":{"type":"string","description":"Only on an end user's own key, in an end user's token's answer: the newest domain of that end user the key already serves (a live or propagating connection of theirs in this application, not the domain asked about), as the widget words it in \"Use your Namecheap access from shop.example.com\". Left out when there is none."}}},"RailInfo":{"type":"object","required":["available"],"properties":{"available":{"type":"boolean"},"reason":{"type":"string","enum":["unknown_provider","provider_has_no_oauth","oauth_client_not_registered","not_discovered","template_not_onboarded","redirect_unavailable","rail_disabled","custom_routing","no_adapter","unregistered","platform_subdomain","provider_not_listed","not_enabled_for_workspace","oauth_available","script_unhealthy","vendor_unavailable","monthly_cap","sign_in_not_wired","site_not_supported","caller_cannot_start","token_not_bound"],"description":"$11b"},"caveat":{"type":"string","description":"A note on an AVAILABLE rail: what the end user must create or qualify for before it works (a GoDaddy Personal Access Token; Namecheap's API eligibility and IP allowlist). Show it; do not treat it as unavailability."},"flow":{"type":"string","enum":["oauth2","vercel_integration","porkbun_handoff","porkbun_dnsconnect","ovh_consent","mcp_oauth"],"description":"Available `oauth` rail only: the sign-in it runs, so a client can label its button (see `POST /connections/{id}/oauth:start`)."},"managed":{"type":"boolean","description":"Available `oauth` rail only: the connect will keep its credential (managed mode). Omitted when it will not."},"regions":{"type":"array","items":{"type":"string","enum":["eu","ca","us"]},"description":"Available `ovh_consent` rail only: the OVHcloud API regions this deployment can run the consent in, the default first."},"key":{"type":"object","description":"Available `cloud_browser` rail only, and only when the sign in also makes a lasting API key for the person's provider account (the provider's key page is one the agent runs). The rail then leads ahead of a pasted API key: nothing is typed, and the key is the one the person would have had to find, name, scope and paste. Names what that key can do and when it ends, so a surface can say so before it asks.","required":["rights","ends_in_days"],"properties":{"name":{"type":"string","description":"The name a key made now would get at the provider (\"CustomDomain Weldon 2026-10-21 1528\"): the application's name, cut to the provider's key page's length and punctuation, then the day and minute (UTC) of this check. The sign-in types it from its own start and adds a four character code of its own at the end (\"CustomDomain Weldon 2026-10-21 1528 3f9a\"), so two sign-ins never make keys of one name; a person finds the key on the provider's page by the name it starts with. A sign in **makes or reuses** a key (it may find one of its own in the account and use that instead of making another), and the session names a new key from its own start, so this is the name to look for, not a promise of the minute. The session's `kept_key` names the key that was kept. Absent for a provider whose key is the account's own and has no name of its own (Namecheap: its API access is turned on and no key is made)."},"delete_url":{"type":"string","format":"uri","description":"The provider's own page that lists and deletes its API keys, for a person who wants the key gone (most providers offer no API to delete one). Absent when none is known."},"rights":{"type":"array","items":{"type":"string","enum":["transfer","billing","account"]},"description":"What the key can do beyond the domain's DNS records: `transfer` (it can transfer the domain away), `billing` (it can make charges), `account` (it has no scopes and holds every right the provider's API gives the account). Empty for a key that reaches DNS only."},"ends_in_days":{"type":["integer","null"],"description":"How long the key lives from the day it is made; null for a key with no end date."}}}}},"DomainCheck":{"type":"object","required":["domain","setup_type"],"properties":{"domain":{"type":"string"},"sandbox":{"type":"boolean","description":"`true` when the check ran for a test mode application: nothing was looked up, the answer is always the manual rail, and the domain must be a reserved `.test` name. Omitted on a real check."},"subdomain":{"type":"string","description":"Server's authoritative Public-Suffix-List parse verdict: the subdomain labels of `domain`, empty string when the domain IS the registrable apex. Clients must adopt this boundary instead of computing their own."},"registrable_domain":{"type":"string","description":"The registrable domain (eTLD+1) of `domain` per the full PSL."},"public_suffix":{"type":"string","description":"The effective TLD (public suffix) of `domain`, e.g. `com`, `co.uk`, `com.ng`."},"provider":{"type":["string","null"]},"setup_type":{"$ref":"#/components/schemas/SetupType"},"supports_automatic":{"type":"boolean"},"oauth_available":{"type":"boolean","description":"the OAuth-into-provider rail can be offered"},"domain_connect":{"type":"boolean","description":"the one-click (Domain Connect sync) rail is offered for this domain. Same predicate as `rails.domain_connect.available`: the provider answered discovery AND, when a provider allowlist is configured (DC_SYNC_PROVIDERS, the default), the provider is on it, i.e. is measured to serve our template catalog. Providers that speak the protocol but have not onboarded our template (GoDaddy, IONOS, Cloudflare) report false even with DC_SYNC_ENABLED on. A domain reported true will not have its domainconnect:start refused for lack of the rail."},"registered":{"type":"boolean","description":"Whether the domain resolves to a delegated zone. OMITTED (not false) when detection failed for a transient reason; only an NXDOMAIN answer reports `false`. Do not tell a user their domain is unregistered unless this field is present and false."},"detection_error":{"type":"string","enum":["nxdomain","resolver"],"description":"Present only on a degraded check (detection failed): `nxdomain` means the domain is not delegated (`registered` is false, `blocked_reason` is `unregistered`); `resolver` means a transient resolver failure; the provider is unknown for now, retry the check."},"authoritative_dns_provider":{"type":["string","null"]},"ns_support":{"type":"object","properties":{"root":{"type":"boolean"},"subdomains":{"type":"boolean"}}},"wildcard_support":{"type":"boolean"},"cname_flattening":{"type":"boolean"},"apex_supported":{"type":"boolean","description":"The provider can serve CNAME-like data at the zone root (ALIAS/ANAME/flattened CNAME). Always agrees with `cname_flattening`. Reported for every check, apex target or not."},"apex_message":{"type":"string","description":"Present only when the record set this check ran against needs an apex record the provider cannot host, i.e. exactly when the apply would refuse with `apex_not_supported`. Gate any warning UI on this field, not on `apex_supported`: a subdomain connect on a provider with no apex capability reports `apex_supported: false` and no message, because nothing in that flow breaks."},"target_mode":{"type":"string","enum":["edge","custom"],"description":"Where this application's domains point: `edge` (proxied by the platform) or `custom` (the application's own connection target, see `PUT /applications/{id}/connect-target`)."},"apex_strategy":{"type":"string","enum":["alias","a_records","unsupported"],"description":"How a ROOT domain is pointed for this application on the detected provider: `alias` (an ALIAS, ANAME or flattened CNAME record to a hostname), `a_records` (address records to `apex_targets`), or `unsupported` (neither is possible; `apex_message` explains)."},"apex_record_type":{"type":"string","description":"The record type to choose in the provider's panel for the root (ALIAS, ANAME, CNAME or A)."},"apex_targets":{"type":"array","items":{"type":"string"},"description":"The addresses a root domain's A records point at when `apex_strategy` is `a_records`."},"spf_override_support":{"type":"boolean"},"caa_support":{"type":"boolean"},"supports_social_login":{"type":"string","description":"yes | no | n-a"},"rails":{"type":"object","description":"Rail truth: per rail, whether it can run for THIS domain right now, and when it can't, one machine reason why. `setup_type: automatic` / `supports_automatic` only ever meant \"an adapter exists\"; this block is what to show a user. Present on every check; a degraded check (detection failed) reports only `manual` available.","properties":{"oauth":{"$ref":"#/components/schemas/RailInfo"},"domain_connect":{"$ref":"#/components/schemas/RailInfo"},"api_key":{"$ref":"#/components/schemas/RailInfo"},"manual":{"$ref":"#/components/schemas/RailInfo"},"cloud_browser":{"$ref":"#/components/schemas/RailInfo","description":"The cloud browser sign in (see `POST /connections/{id}/browser:start`). Present only while the deployment has it on; absent otherwise."},"nameservers":{"type":"object","description":"The DNS hosting verdict: whether the application offers to host the domain's DNS by moving its nameservers (`nameserver_migration`), and where it stands among the other ways. Absent while the application's setting is off.","required":["verdict","reason"],"properties":{"verdict":{"type":"string","enum":["offered","offered_first","recommended","unavailable"],"description":"`offered`: after the other ways. `offered_first`: the application's setting is `prefer`. `recommended`: hosting saves the person the most for this domain (`reason` says why: no automatic way works, or the records are many). `unavailable`: offered, but not for this domain (`reason` says why)."},"reason":{"type":"string","enum":["application_offers","application_prefers","no_automatic_way","many_records","plan_zone_limit","registrar_locks_nameservers","disabled","platform_subdomain","unsupported_tld","reserved"],"description":"Why. `application_offers` and `application_prefers`: the application's setting. `no_automatic_way`: nothing but copying records by hand works for this domain. `many_records`: the domain needs four or more records, a lot to copy by hand. `plan_zone_limit`: hosting would lead, but the workspace holds as many hosted zones as its plan counts (or CustomDomain™ is near its own limit), so it is offered after the other ways; the verdict is then `offered`. For `unavailable`, the reason of `nameserver_migration` (`registrar_locks_nameservers`, and the reasons of `managed_dns`: `disabled`, `platform_subdomain`, `unsupported_tld`, `reserved`)."}}},"saved_access":{"type":"object","description":"The kept keys that may act for this domain for the caller, best first (see `GET /connections/{id}/saved-access`): no sign in and no new key. Present only when there is one, and then `recommended_rail` is `saved_access`. An API key caller has the workspace's keys; an end user's widget token has that end user's own, under the conditions of `GET /connections/{id}/saved-access`; a delegated agent token never gets the block.","required":["available","accounts"],"properties":{"available":{"type":"boolean"},"accounts":{"type":"array","items":{"$ref":"#/components/schemas/SavedAccess"}}}}}},"also_provider":{"type":"object","description":"The second way, when the registrar and the nameservers name two providers: a former Google Domains name (now Squarespace's) keeps Google's `ns-cloud-*.googledomains.com` nameservers, which Google Cloud DNS zones use too. `provider` is then the registrar's (`squarespace`, found over RDAP, so its secure sign-in is offered) and this is the nameservers' (`gcpdns`). Absent otherwise, and when the registrar lookup answers nothing.","required":["provider","provider_name","reason"],"properties":{"provider":{"type":"string"},"provider_name":{"type":"string"},"reason":{"type":"string","enum":["former_google_domains"]}}},"recommended_rail":{"type":"string","enum":["saved_access","oauth","domain_connect","cloud_browser","api_key","manual"],"description":"The rail the server recommends: `saved_access` when the caller already keeps a key that may act for the domain, else by precedence oauth → domain_connect → cloud_browser → api_key → manual (least typing for the end user first). `cloud_browser` is recommended only when it is available and the API key rail is unavailable, carries a caveat, or the sign in makes the API key itself (`rails.cloud_browser.key`). Absent when `blocked_reason` is set. The console and the widget follow this field so the surfaces never disagree."},"end_user_automatic":{"type":"boolean","description":"True when the recommended rail needs nothing typed by the end user (OAuth or one-click). This is the fact `supports_automatic` was always misread as. An API-key rail is \"automatic\" only for someone holding an API key."},"blocked_reason":{"type":"string","enum":["unregistered","platform_subdomain"],"description":"Present when no rail can connect this domain. `unregistered`: no nameserver delegation at all (fix it at the registrar). `platform_subdomain`: a hosting platform's own subdomain (www..vercel.app). Its DNS is the platform's; `POST /v1/connections` refuses it with `platform_subdomain`."},"dashboard_url":{"type":"string","description":"Best-effort deep link into the detected provider's DNS panel for this zone, to send the user to when they add records by hand. Absent when unknown."},"nameservers":{"type":"array","items":{"type":"string"},"description":"The nameserver delegation the detector observed (normalized hostnames)."},"managed_dns":{"$ref":"#/components/schemas/ManagedDNSAvailability"},"nameserver_migration":{"$ref":"#/components/schemas/NameserverMigrationOffer"},"integration_warnings":{"type":"array","description":"Problems with how YOU configured the integration, not with the end user's domain. They are returned only when you supplied your own `records`. The widget never renders these; they are for your logs and your developers.\n\nPresent because this class of failure is invisible to the party who can fix it: an integrator testing with `www.` sees everything work and ships, and only their end users hit the wall.","items":{"type":"object","properties":{"code":{"type":"string","enum":["supplied_apex_unrealizable"],"description":"`supplied_apex_unrealizable`: you supplied a record for the zone apex pointing at your own host, and this domain's DNS provider has no ALIAS/ANAME/CNAME-flattening type, so a hostname cannot sit at a root there. Providers WITH flattening (Cloudflare, Route 53, DNSimple) accept it unchanged."},"message":{"type":"string","description":"Human-readable, with the available alternatives named."}}}},"record_conflicts":{"type":"array","description":"Existing DNS records the automatic write would replace (`value-mismatch`, `cname-collision`, `spf-merge`); these count toward `will_fallback_to_manual`. Within /v1 a `caa-blocks-letsencrypt` advisory is also listed here, as before `advisories` existed; it never counts toward the fallback, and new clients should read it from `advisories`.","items":{"type":"object","properties":{"kind":{"type":"string","description":"value-mismatch | cname-collision | spf-merge | caa-blocks-letsencrypt"},"host":{"type":"string"},"type":{"type":"string"},"existing":{"type":"string"},"desired":{"type":"string"}}}},"advisories":{"type":"array","description":"Warnings that are not a record the automatic write would replace, so they never count toward `will_fallback_to_manual`. Today one kind: `caa-blocks-letsencrypt`, a CAA record that does not authorize Let's Encrypt, which blocks the certificate; the fix is to add a CAA record for `letsencrypt.org` next to the existing ones, never to remove them. Returned only when the application's domains route to the edge.","items":{"type":"object","properties":{"kind":{"type":"string","description":"caa-blocks-letsencrypt"},"host":{"type":"string"},"type":{"type":"string"},"existing":{"type":"string"},"desired":{"type":"string"}}}},"conflict_tolerance":{"type":"integer","description":"Provider's automated-write conflict threshold (0/absent = no modeled limit)."},"will_fallback_to_manual":{"type":"boolean","description":"True when current record conflicts exceed the provider's threshold, so an automated flow would silently drop to manual. Have the user clear conflicts first."}}},"ProviderInfo":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"rail":{"type":"string","description":"dc | oauth | api | manual"},"oauth":{"type":"boolean"},"account_ways":{"type":"array","description":"The ways to add this company's account in Connected accounts, easiest first: `oauth` (the person signs in with the company and the account is made from the OAuth grant, kept with its refresh token; `POST /provider-accounts:oauth-start`, the console only), then `secure_sign_in` (the person signs in at the company and CustomDomain™ makes the key; `POST /provider-accounts:sign-in`, the console only), then `api_key` (the person pastes a key; `POST /provider-accounts`). Always present; `[]` for a company that only signs in and takes no key. `secure_sign_in` is listed only while the deployment runs it for the company (the feature on, its key page and its domain list in place); the workspace's own gates are the sign in's to apply. `oauth` is listed only while the deployment runs the company's OAuth app, keeps what it hands back and the company's sign-in needs no domain; a company that lists it lists no `secure_sign_in`.","items":{"type":"string","enum":["oauth","secure_sign_in","api_key"]}}}},"LeftKey":{"type":"object","required":["name"],"description":"A key the agent made at the provider and CustomDomain™ does not keep, still live in the person's account.","properties":{"name":{"type":"string","description":"The name the key was made with","to find it at the provider.":null},"page":{"type":"string","description":"The provider's page that lists and deletes keys; absent when none is known."}}},"AccountSignInSession":{"type":"object","required":["id","purpose","state","provider","provider_name"],"description":"An account sign in as the console reads it (`GET /browser-sessions/{sid}` with the console's own API key call). Not the popup's view: it holds no live view address, relay socket or token, and never the key.","properties":{"id":{"type":"string"},"purpose":{"type":"string","enum":["account"]},"state":{"type":"string","enum":["created","awaiting_sign_in","checking","key_ready","done","cancelled","expired","abandoned","failed"],"description":"`key_ready`: the key is made and checked and waits for `:keep`. `done`: kept. Every other end left the key at the provider (`left_key`) when one was made."},"provider":{"type":"string"},"provider_name":{"type":"string"},"application_id":{"type":"string","description":"The application the key is for; absent for a key that serves the whole workspace."},"renews_account_id":{"type":"string","description":"The provider account a renewal sign in (`POST /provider-accounts/{id}/reconnect` with `method` `secure_sign_in`) makes the key for; absent for a sign in that adds an account."},"deadline":{"type":"string","format":"date-time","description":"In `key_ready`: when the wait for the keep step ends."},"zones":{"type":"array","items":{"type":"string"},"description":"In `key_ready`: the registrable domains the key lists, lower case. `[]` for a key that reaches none yet."},"key":{"type":"object","required":["rights"],"description":"In `key_ready`: what the key is.","properties":{"name":{"type":"string"},"page":{"type":"string","description":"The provider's page that lists and deletes keys."},"rights":{"type":"array","items":{"type":"string"},"description":"What the key can do beyond DNS records; empty for a key that reaches DNS only."},"expires_at":{"type":"string","format":"date-time"}}},"left_key":{"$ref":"#/components/schemas/LeftKey"},"error":{"type":"object","description":"In `failed`: why, in the words the person is shown.","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"AccountKept":{"type":"object","required":["account","swapped"],"properties":{"account":{"$ref":"#/components/schemas/ProviderAccount"},"swapped":{"type":"boolean","description":"True when the key went into an account the workspace already held."},"replaced_key":{"$ref":"#/components/schemas/ReplacedKey"}}},"ReplacedKey":{"type":"object","required":["name"],"description":"The key a swap took out of use: it is no longer the account's key, and it still lives at the provider (nothing is revoked automatically). Present only when the swap replaced a different key that has a name; absent for a new account and when the new key is the same key.","properties":{"name":{"type":"string","description":"The name the replaced key was made with, to find it at the provider. Every sign in ends its key's name in a code of its own (and an account sign in names it to the second), so it differs from the new key's name."},"page":{"type":"string","description":"The provider's page that lists and deletes keys; absent when none is known."}}},"Usage":{"type":"object","description":"Metered usage for ONE calendar month, for the tenant the credential belongs to (never a query parameter). `org`, `period`, `used` and `mode` are always present; the plan block below it is present whenever the org resolves to a billing record, which is every legitimate tenant (a new workspace starts on `starter`). `status`, `has_billing_account` and `billing_state` are billing data: they are sent only to a credential holding `billing:manage` (owners and admins, and a workspace's own non-member API key), never to a member's or viewer's key or a widget token.","required":["org","period","used","mode"],"properties":{"org":{"type":"string","description":"The tenant the usage belongs to, derived from the authenticated credential."},"period":{"type":"string","examples":["2026-07"],"description":"UTC calendar month, `YYYY-MM`."},"used":{"type":"integer","description":"metered domain connections this period (one calendar month). Compare `quota_used`, not this, with `quota`."},"mode":{"type":"string","enum":["test","live",""],"description":"The Stripe key mode the control plane is running against; empty when billing is unconfigured."},"plan":{"$ref":"#/components/schemas/PlanId"},"plan_name":{"type":"string","description":"The plan's display name, e.g. `Growth`."},"quota":{"type":"integer","description":"The plan's included domain connections over `quota_window_months` calendar months ending with `period`: 10 over 12 months on `starter` (and the retired `free`), the plan's `domains_per_year` divided by 12 and rounded up over one month on every other plan (`0` = unlimited). Compare `quota_used` against this. `limit` carries the identical value."},"quota_used":{"type":"integer","description":"Metered domain connections over the quota window, the count `quota` is compared with. Equal to `used` on a plan whose window is one month."},"quota_window_months":{"type":"integer","description":"How many calendar months `quota` and `quota_used` cover, ending with `period`: 12 on `starter`, 1 on every other plan."},"limit":{"type":"integer","description":"Alias of `quota`, carrying the identical value. This schema declared `limit` while the handler emitted only `quota`; rather than break either reader, both are emitted. Prefer `quota` in new code."},"metered":{"type":"boolean","description":"`true` on tiers priced for overage (`growth`, `enterprise`). It carries NO enforcement meaning; it describes pricing only. Read `hard_cap` for the plan's refusal policy and `quota_enforced` for whether a `402` is possible right now. Never branch on this field."},"hard_cap":{"type":"boolean","description":"Whether this PLAN refuses connections past `quota` (`402 quota_exceeded`) rather than allowing and recording them as overage. `true` only on the entry tiers: `starter` ($10 a month) and the retired `free`. Every larger tier (`startup`, `premium`, `growth`, `enterprise`) is `false` and is never refused at quota. The refusal reaches the tenant's own end users through the embedded widget, so it is worded neutrally for them. Independent of the deployment's `BILLING_ENFORCE_QUOTA`; combine the two via `quota_enforced`."},"quota_state":{"type":"string","enum":["ok","approaching","at_limit"],"description":"The server's classification of `quota_used` against `quota`. `approaching` means at or past 80% of quota; `at_limit` means `quota_used >= quota`. Always `ok` on an unlimited plan (`quota <= 0`)."},"quota_enforced":{"type":"boolean","description":"Whether an over-quota connection would actually be refused with `402 quota_exceeded` right now. True only when the plan's `hard_cap` is set AND the deployment enables enforcement. A client cannot infer the second half, which is why this is served rather than derived. On every paid tier it is `false` at any usage level. A tenant may therefore be `at_limit` with `quota_enforced: false` (over the line with nothing refused), so never treat `at_limit` alone as \"blocked\". Always `false` on an unlimited plan."},"remaining":{"type":"integer","description":"`quota - quota_used`, floored at `0`. Omitted entirely on an unlimited plan, where no remainder is meaningful."},"status":{"type":"string","description":"Subscription status mirrored from Stripe, e.g. `active`, `past_due` (empty for a workspace that has not subscribed). Owners and admins only."},"has_billing_account":{"type":"boolean","description":"`true` when a Stripe customer exists for the org, i.e. the billing portal is available. Owners and admins only."},"billing_state":{"$ref":"#/components/schemas/BillingState"}}},"WebhookEndpoint":{"type":"object","required":["id","url"],"properties":{"id":{"type":"string"},"application_id":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"secret":{"type":["string","null"],"description":"Present ONLY in the creation response (whsec_…). Deliveries are signed with it: each POST carries X-JE-Timestamp (unix seconds) and X-JE-Signature (sha256=hex of HMAC-SHA256 over \".\"). Reject deliveries whose timestamp is outside a ~5-minute window."},"created_at":{"type":"string","format":"date-time"}}},"WebhookDelivery":{"type":"object","required":["id","event_type"],"properties":{"id":{"type":"string"},"endpoint_id":{"type":"string"},"application_id":{"type":"string"},"url":{"type":"string","format":"uri"},"event_id":{"type":"string"},"event_type":{"type":"string"},"domain":{"type":"string"},"attempts":{"type":"integer"},"status_code":{"type":"integer","description":"HTTP status of the final attempt (0 = no response)"},"delivered":{"type":"boolean"},"error":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"CertStatus":{"type":"string","enum":["pending","issued","renewing","failed","revoked"]},"Certificate":{"type":"object","required":["domain","status","managed"],"properties":{"id":{"type":"string"},"domain":{"type":"string"},"application_id":{"type":"string"},"status":{"$ref":"#/components/schemas/CertStatus"},"issuer":{"type":"string"},"not_before":{"type":"string","format":"date-time"},"not_after":{"type":"string","format":"date-time"},"last_error":{"type":"string","description":"most recent issuance/renewal failure; empty when healthy."},"managed":{"type":"boolean","description":"true = edge auto-manages (ACME); false = operator-imported."},"renew_after":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Eligibility":{"type":"object","required":["domain","eligible"],"properties":{"domain":{"type":"string"},"eligible":{"type":"boolean"},"reason":{"type":"string","description":"why not, when ineligible; empty when eligible."}}},"ApplicationDefaultOrigin":{"type":"object","properties":{"application_id":{"type":"string"},"default_origin":{"type":"string","description":"Absent when no default is set."},"configured":{"type":"boolean","description":"Whether a default is set. Distinguishes \"no default\" from an empty value."}}},"PowerConfig":{"type":"object","required":["connection_id","domain","powered","www_redirect"],"properties":{"connection_id":{"type":"string"},"domain":{"type":"string"},"origin":{"type":"string","description":"the URL the edge reverse-proxies to."},"powered":{"type":"boolean","description":"true when an origin is registered."},"www_redirect":{"type":"boolean","description":"serve an apex↔www redirect."},"redirect_to":{"type":"string","description":"when set, the edge 301s the host here."},"root_path_access":{"type":"array","items":{"type":"string"}}}},"PowerConfigInput":{"type":"object","properties":{"application_url":{"type":"string","format":"uri","description":"origin the edge proxies to; required to enable, optional to re-power (kept if omitted)."},"www_redirect":{"type":"boolean"},"redirect_to":{"type":"string","description":"set to a URL to 301 the host there; \"\" clears it."},"root_path_access":{"type":"array","items":{"type":"string"}}}},"BulkResult":{"type":"object","required":["domain","status"],"properties":{"domain":{"type":"string"},"connection_id":{"type":"string"},"status":{"type":"string","enum":["connected","already","failed"]},"message":{"type":"string"}}},"CheckoutSession":{"type":"object","description":"A Stripe Checkout session for the embedded or elements payment form.","required":["id"],"properties":{"id":{"type":"string","examples":["cs_test_123"]},"url":{"type":"string","format":"uri","description":"hosted checkout URL (unused for embedded and elements sessions)."},"client_secret":{"type":"string","description":"mount Stripe Embedded Checkout or the elements checkout with this."},"ui_mode":{"type":"string","enum":["embedded","elements"],"description":"How the session was really created. An `elements` request answers `embedded` when Stripe could not create an Elements session. A domain payment has no redirect flow, so it is never `hosted`."}}},"SellOrderView":{"type":"object","description":"The stable, documented projection of a domain-purchase order.","required":["orderId","domain","status"],"properties":{"orderId":{"type":"string","examples":["ord_1a2b3c"]},"domain":{"type":"string"},"registrar":{"type":"string"},"status":{"type":"string","enum":["quoted","purchasing","purchased","transferred","failed","expired"]},"createdAt":{"type":"string","format":"date-time"},"regOrderId":{"type":"string","description":"the registrar's order reference, once purchased."},"jobId":{"type":"string"},"link":{"type":"string","description":"sharing-rail checkout URL, if any."},"freeDomain":{"type":"boolean","description":"promo (first-domain-free) registration."}}},"SellOrder":{"type":"object","description":"The finalized order record returned by fulfillment. Its stable, documented projection is available via `GET /v1/sell/orders/{id}` (`SellOrderView`); additional internal fields may be present here.","additionalProperties":true,"properties":{"Domain":{"type":"string"},"Registrar":{"type":"string"},"RegOrderID":{"type":"string"}}},"NameserverTarget":{"type":"object","description":"Where a domain's nameservers move. `managed`: CustomDomain™ hosts the zone (route 1). `dns_host`: a zone we create in the platform's own DNS host account, a connected provider account with continuous access at Cloudflare, Amazon Route 53, Google Cloud DNS or Azure DNS (route 2a). `custom`: the platform's own nameservers, 2 to 13 host names, whose zone the platform runs (route 2b).","required":["kind"],"properties":{"kind":{"type":"string","enum":["managed","dns_host","custom"]},"provider":{"type":"string","description":"For `dns_host`: the DNS host (an adapter id such as `cloudflare`). Set from the account."},"account_id":{"type":"string","description":"For `dns_host`: the connected provider account (`POST /provider-accounts`, continuous access). Saving it takes an admin, an owner or the member who connected it (`403 forbidden` for another member's); the account the application already has may be kept by anyone who may change the setting."},"nameservers":{"type":"array","minItems":2,"maxItems":13,"items":{"type":"string"},"description":"For `custom`: the nameserver host names, stored lower case without a trailing dot."}}},"NameserverMigrationSetting":{"type":"object","description":"Whether and how the application offers to move an end user's nameservers. It is the one switch for every DNS hosting offer the widget makes. `off` (the default): never offered, and the setting is omitted; a widget token can't start managed DNS either, nor while the target is `dns_host` or `custom`. `offer`: the widget shows the move as a quiet second choice beside adding records. `prefer`: the move is the first choice. Send `{\"mode\": \"off\"}` to clear it.","required":["mode","target"],"properties":{"mode":{"type":"string","enum":["off","offer","prefer"]},"target":{"$ref":"#/components/schemas/NameserverTarget"}}},"NameserverMigrationOffer":{"type":"object","description":"What the widget offers for this domain, present only when the calling application's `nameserver_migration.mode` is `offer` or `prefer`.","required":["mode","target","available","path"],"properties":{"mode":{"type":"string","enum":["offer","prefer"]},"target":{"type":"string","enum":["managed","dns_host","custom"]},"dns_host":{"type":"string","description":"The DNS host of target `dns_host`."},"available":{"type":"boolean"},"reason":{"type":"string","enum":["disabled","platform_subdomain","unsupported_tld","reserved","registrar_locks_nameservers"],"description":"Why the nameservers can't move, when `available` is false: the reasons of `managed_dns`, or `registrar_locks_nameservers` (the domain is registered at a registrar that requires its own nameservers, Cloudflare Registrar; moving them needs a transfer first)."},"path":{"type":"string","enum":["agent","manual"],"description":"How the widget's move would change them: `agent`, the end user signs in to their registrar in the cloud browser and approves the new nameservers; `manual`, they set them with the values shown. A connection linked to a connected account changes them through the registrar's API instead."},"provider":{"type":"string","description":"Where the nameservers would be changed: the registrar's provider id when `registrar` names one we route to, else the detected DNS host as a guess (then `registrar` is null and nothing names it)."},"registrar":{"description":"Who the domain is registered with, from RDAP; null when unknown.","oneOf":[{"$ref":"#/components/schemas/NameserverRegistrar"},{"type":"null"}]},"nameservers":{"type":"array","items":{"type":"string"},"description":"The new nameservers for target `custom`. For `managed` and `dns_host` they are known once the zone exists (the migration's `new_nameservers`)."}}},"NameserverStartOffer":{"type":"object","description":"Whether one domain's nameservers can move to DNS hosting now and how (`GET /connections/{id}/nameservers:offer`).","required":["available","zone","setting","target","registrar","paths"],"properties":{"available":{"type":"boolean"},"reason":{"type":"string","enum":["missing_scope","ns_not_offered","dns_host_unavailable","move_open","registrar_locks_nameservers","disabled","platform_subdomain","unsupported_tld","reserved","zone_limit","plan_zone_limit"],"description":"Why the move cannot start, when `available` is false."},"zone":{"type":"string","description":"The registrable domain whose nameservers move."},"setting":{"type":"string","enum":["off","offer","prefer"],"description":"The application's DNS hosting mode. A start from an API key or the console is allowed whatever it says."},"target":{"type":"string","enum":["managed","dns_host","custom"],"description":"Where the move hosts the zone: the application's setting, else `managed`."},"dns_host":{"type":"string","description":"The DNS host of target `dns_host` (an adapter id)."},"nameservers":{"type":"array","items":{"type":"string"},"description":"The platform's own nameservers, for target `custom`."},"registrar":{"description":"Who the domain is registered with, from RDAP; null when unknown or not looked up (an earlier `reason` held).","oneOf":[{"$ref":"#/components/schemas/NameserverRegistrar"},{"type":"null"}]},"paths":{"type":"object","required":["api","agent","manual"],"properties":{"api":{"type":"object","required":["available","accounts"],"properties":{"available":{"type":"boolean","description":"True when at least one account may be named."},"accounts":{"type":"array","items":{"type":"object","required":["id","label","provider","provider_name","how"],"properties":{"id":{"type":"string","description":"Send it as `provider_account_id`."},"label":{"type":"string"},"provider":{"type":"string"},"provider_name":{"type":"string"},"how":{"type":"string","enum":["api_key","secure_sign_in"],"description":"How the key came: a person pasted it, or the cloud browser made it at a secure sign in."}}}}}},"agent":{"type":"object","required":["available"],"properties":{"available":{"type":"boolean","description":"The cloud browser can change this registrar's nameservers."}}},"manual":{"type":"object","required":["available"],"properties":{"available":{"type":"boolean","description":"Always true when the move can start."}}}}}}},"NameserverRegistrar":{"type":"object","description":"The company a domain is registered with, where its nameservers are changed. Looked up over RDAP at the TLD's registry (found through the IANA bootstrap file) and matched to a provider by its IANA Registrar ID, so a domain registered at GoDaddy with its DNS at Cloudflare is changed at GoDaddy.","required":["name","source"],"properties":{"name":{"type":"string","description":"The brand (\"GoDaddy\"), the reseller the registry names, or RDAP's own name."},"provider":{"type":"string","description":"Our provider id for it, when we route to it (`godaddy`)."},"iana_id":{"type":"integer","description":"The IANA Registrar ID, when the registry gives one."},"url":{"type":"string","description":"The registrar's website."},"source":{"type":"string","enum":["rdap","request","account",""],"description":"`rdap`: looked up. `request`: the caller named it with a key or an account. `account`: RDAP said nothing, and a connected account read the domain's registration. Empty: RDAP named a registrar we do not route to (`name` only)."}}},"NameserverMigrateRequest":{"type":"object","additionalProperties":false,"properties":{"target":{"$ref":"#/components/schemas/NameserverTarget"},"path":{"type":"string","enum":["api","agent","manual"],"description":"How to change the nameservers. Omitted: `api` with a key, else `agent` where the cloud browser can, else `manual`."},"provider":{"type":"string","description":"The registrar a `credential` belongs to (an adapter id such as `godaddy`). When RDAP names the domain's registrar, a key at another company is refused (`registrar_mismatch`)."},"provider_account_id":{"type":"string","description":"A connected provider account at the domain's registrar. One at another company than the registrar RDAP names is refused (`registrar_mismatch`), and so is one the caller may not use (`403 forbidden`: an API key of a member may use the accounts an admin or an owner connected and its own member's, not another member's)."},"credential":{"type":"object","additionalProperties":false,"required":["token"],"properties":{"token":{"type":"string","description":"A registrar API key the customer created, in the adapter's format. Used for this call only and never stored."}}},"zone_ready":{"type":"boolean","description":"Target `custom`: the platform's nameservers now serve the zone."},"skip_zone_check":{"type":"boolean","description":"Target `custom`: do not check that the new nameservers answer for the zone before moving."},"copy_reviewed":{"type":"boolean","description":"A person checked the copied records (state `needs_review`), so the move may go on. Sent with the start by an API key, it accepts a copy read from public DNS in advance; it does not cover a copy that read nothing, which always waits for a person. A widget token may send it only to a move already in `needs_review`."},"consent":{"type":"object","additionalProperties":false,"required":["id","version"],"properties":{"id":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,64}$"},"version":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,64}$"}},"description":"The consent text the end user agreed to. Required from a widget token, and it must name a text the widget shows (`nsm-consent`, versions 1 to 3), so a stored consent always names the words that were on the screen."}}},"NameserverRollbackRequest":{"type":"object","additionalProperties":false,"properties":{"rollback_target":{"type":"string","enum":["previous","registrar_default"],"description":"Where to move back. `previous`: the nameservers the domain had (refused with `409 old_dns_gone` when they no longer answer for the zone, as after Cloudflare deleted a moved zone). `registrar_default`: the registrar's own DNS, through its reset call where it has one (Namecheap, Spaceship, Name.com, Porkbun, Hostinger), the cloud browser, or the person. Omitted: `previous` while the old nameservers still answer, else `registrar_default` (the migration's `rollback_default`)."},"provider_account_id":{"type":"string","description":"A connected account the caller may use, at the registrar the move named (`403 forbidden` for another member's, `422 registrar_mismatch` for another company's)."},"credential":{"type":"object","additionalProperties":false,"required":["token"],"properties":{"token":{"type":"string"}}},"consent":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"version":{"type":"string"}}}}},"NameserverMigration":{"type":"object","required":["id","zone","state","path","target","registrar","old_nameservers","new_nameservers","observed_nameservers","records_copied","email_records","email_kinds","copy_warnings","ds_present","can_rollback","rollback_targets","old_dns_serves","next_action","created_at","updated_at"],"properties":{"id":{"type":"string"},"connection_id":{"type":"string"},"zone":{"type":"string","description":"The registrable domain whose nameservers move."},"state":{"type":"string","enum":["pending","copying","needs_review","needs_dnssec_off","waiting_ds","setting","propagating","active","failed","rolled_back"],"description":"`pending`: target `custom` waits for the platform's zone. `copying`: the zone is being created and the records copied; a copy whose write to the DNS servers failed is retried, never switched to. `needs_review`: the copy is not proven complete (it was read from public DNS, which can't list a zone, or some records could not be carried over); a person checks `copy_warnings` and confirms with `copy_reviewed`. `needs_dnssec_off`: DNSSEC must be turned off at the registrar first. `waiting_ds`: DNSSEC is off; waiting for the registry to stop publishing the DS record and its TTL to pass. `setting`: the nameservers are being changed (`waiting_for` says by whom). `propagating`: changed; waiting for the registry to list every new nameserver (checked every 5 minutes for 2 hours, then hourly up to 48 hours). `active`: the registry lists them (re-checked every 6 hours; a move away is `failed` with `delegation_drift`). `failed`: see `failure_code`. `rolled_back`: moved back."},"path":{"type":"string","enum":["api","agent","manual"]},"target":{"type":"string","enum":["managed","dns_host","custom"]},"dns_host":{"type":"string","description":"The DNS host of target `dns_host` (an adapter id such as `cloudflare`)."},"provider":{"type":"string","description":"Where the nameservers are changed: the registrar's provider id (`registrar.provider`), or, when `registrar` is null, the DNS host the domain used, as a guess (then `next_step` says \"where the domain is registered\" and names no company)."},"registrar":{"description":"Who the domain is registered with (RDAP, or the account or key the caller brought); null when unknown.","oneOf":[{"$ref":"#/components/schemas/NameserverRegistrar"},{"type":"null"}]},"old_dns_host":{"type":"string","description":"The DNS host the domain used when the move started (a provider id such as `cloudflare`)."},"old_nameservers":{"type":"array","items":{"type":"string"},"description":"What the registry listed when the move started; a rollback sets these."},"new_nameservers":{"type":"array","items":{"type":"string"}},"observed_nameservers":{"type":"array","items":{"type":"string"},"description":"What the registry listed at the last check."},"waiting_for":{"type":"string","enum":["zone_ready","zone_served","copy_review","dnssec_off","ds_clear","credential","registrar_confirm","browser_session","registrar","delegation"]},"next_step":{"type":"string","description":"One sentence for a person."},"next_action":{"description":"$11c","oneOf":[{"$ref":"#/components/schemas/NameserverNextAction"},{"type":"null"}]},"failure_code":{"type":"string","enum":["zone_copy_failed","zone_not_served","dnssec_timeout","ds_removal_failed","credential_refused","registrar_refused","registrar_locked","changed_elsewhere","agent_failed","delegation_timeout","delegation_drift","internal"],"description":"`changed_elsewhere`: the registrar listed other nameservers than the ones the move started from, so the change did not overwrite them."},"failure_detail":{"type":"string"},"records_copied":{"type":"integer"},"email_records":{"type":"integer","description":"How many of the copied records carry mail (MX, SPF, DKIM, DMARC)."},"email_kinds":{"type":"array","items":{"type":"string","enum":["mx","spf","dkim","dmarc"]}},"copy_source":{"type":"string","enum":["api","discovery","existing_zone"],"description":"How the records were copied. `api`: the whole zone, read through a key we hold at the DNS host the domain used (a kept sign in or a connected account there); proven complete. `discovery`: read from public DNS at the names domains commonly use; a person confirms it. `existing_zone`: the platform's zone already held records, which were kept."},"copy_warnings":{"type":"array","items":{"type":"string"},"description":"What a person should check before the switch: records left out (a Cloudflare proxied record answers with Cloudflare's addresses, not the origin), lookups that went unanswered, forwarding that stays at the old host."},"copy_reviewed_at":{"type":"string","format":"date-time","description":"When a person confirmed a copy that is not proven complete."},"ds_present":{"type":"boolean","description":"The registry published a DS record (DNSSEC was on) during the move."},"ds_removed_at":{"type":"string","format":"date-time"},"ds_cleared_at":{"type":"string","format":"date-time"},"can_rollback":{"type":"boolean"},"rollback_path":{"type":"string","enum":["api","agent","manual","none"],"description":"How the move back was made: `api` (the registrar's API, done), `agent` (the person signs in to the registrar in the cloud browser with `purpose: nameservers` and approves it), `manual` (`next_step` says what to set or choose), `none` (nothing had changed yet)."},"rollback_targets":{"type":"array","items":{"type":"string","enum":["previous","registrar_default"]},"description":"The move backs possible now; `previous` is left out once the old nameservers no longer answer for the zone."},"rollback_default":{"type":"string","enum":["previous","registrar_default"],"description":"Where a move back without `rollback_target` goes."},"rollback_target":{"type":"string","enum":["previous","registrar_default"],"description":"Where the move back went."},"rollback_set_at":{"type":"string","format":"date-time","description":"When the move back was made at the registrar; absent while a person or the cloud browser still has it to do."},"old_dns_serves":{"type":["boolean","null"],"description":"Whether the old nameservers still answered for the zone when last asked (once a day while active, and at a move back); null when not asked yet."},"consent":{"type":"object","required":["id","version","at"],"properties":{"id":{"type":"string"},"version":{"type":"string"},"at":{"type":"string","format":"date-time"}}},"actor":{"type":"string","enum":["end_user","api_key","console","agent"]},"created_at":{"type":"string","format":"date-time"},"set_at":{"type":"string","format":"date-time","description":"When the nameservers were changed at the registrar (or first seen changed)."},"active_at":{"type":"string","format":"date-time"},"failed_at":{"type":"string","format":"date-time"},"rolled_back_at":{"type":"string","format":"date-time"},"drifted_at":{"type":"string","format":"date-time"},"checked_at":{"type":"string","format":"date-time"},"next_check_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"NameserverNextAction":{"type":"object","required":["kind","method","path"],"description":"A request that moves a nameserver migration on, with the connection's id filled in. The caller adds what it always adds to that route.","properties":{"kind":{"type":"string","enum":["sign_in","retry","rollback"],"description":"`sign_in`: the move waits for the cloud browser (state `needs_dnssec_off` or `setting` on path `agent`, or a move back whose `rollback_path` is `agent` and not yet made), so the person signs in to their registrar and approves what will change. The request is the registrar sign in's start. `retry`: the move failed before anything was changed at the registrar (`can_rollback` is false); the start call with this `body` begins the same move again, on the same path and, for `api` with a connected account, with that account, where a start with no body picks them afresh (a move made with a key sent once keeps no account: its retry is `{path: api}` and the key is sent again; the end user's start also sends `consent`). `rollback`: the move failed after the registrar was changed or asked (`can_rollback` is true), and moving back is the safe way out, to where a move back without a choice goes (`rollback_default`)."},"method":{"type":"string","enum":["POST"]},"path":{"type":"string","description":"The route: `/v1/connections/{id}/browser:start` for `sign_in`, `/v1/connections/{id}/nameservers:migrate` for `retry`, `/v1/connections/{id}/nameservers:rollback` for `rollback`."},"body":{"type":"object","additionalProperties":true,"description":"The fields the route needs beyond the ones the caller always sends. `sign_in`: `purpose` `nameservers` and the registrar's `provider` (the caller adds `return_origin` and `consent_version`). `rollback`: `rollback_target`. `retry`: the move's `path`, and for `api` with a connected account that account's `provider_account_id` (a widget token reads the path only: it may not name an account; a move made with a key sent once has none, so only `{path: api}`), absent when the move recorded no path. A caller who may not use that account is refused `403 forbidden`."}}},"NameserverMigrationStats":{"type":"object","required":["by_state","by_path","by_target","by_registrar","by_old_dns_host","total","started","active","median_seconds_to_active","dnssec_waits","median_seconds_dnssec_wait","failures_by_code","rolled_back","drifted"],"properties":{"by_state":{"type":"object","additionalProperties":{"type":"integer"}},"by_path":{"type":"object","additionalProperties":{"type":"integer"}},"by_target":{"type":"object","additionalProperties":{"type":"integer"}},"by_registrar":{"type":"object","additionalProperties":{"type":"integer"},"description":"Moves by the registrar's provider id; `unknown` when RDAP named none we route to."},"by_old_dns_host":{"type":"object","additionalProperties":{"type":"integer"},"description":"Moves by the DNS host the domain left; `unknown` when none was detected."},"total":{"type":"integer"},"started":{"type":"integer"},"active":{"type":"integer"},"median_seconds_to_active":{"type":"integer"},"dnssec_waits":{"type":"integer","description":"Migrations that found DNSSEC on."},"median_seconds_dnssec_wait":{"type":"integer","description":"The median time from the start until the registry stopped publishing the DS record."},"failures_by_code":{"type":"object","additionalProperties":{"type":"integer"}},"rolled_back":{"type":"integer"},"drifted":{"type":"integer"}}},"NameserverEventData":{"type":"object","description":"The `nameservers` object of every `nameservers.*` webhook.","required":["migration_id","zone","state","path","target","old_nameservers","new_nameservers"],"properties":{"migration_id":{"type":"string"},"zone":{"type":"string"},"state":{"type":"string"},"path":{"type":"string"},"target":{"type":"string"},"old_nameservers":{"type":"array","items":{"type":"string"}},"new_nameservers":{"type":"array","items":{"type":"string"}},"observed_nameservers":{"type":"array","items":{"type":"string"}},"failure_code":{"type":"string"},"records_copied":{"type":"integer"},"email_records":{"type":"integer"}}},"ManagedDNSAvailability":{"type":"object","description":"Whether CustomDomain™ can host this domain's zone (managed DNS). Always present on the domains:check response. It is the deployment's and the domain's verdict only: whether the end user is offered DNS hosting is the application's `nameserver_migration` setting, and a widget token can start managed DNS only when that setting is on with target `managed`.","required":["available","reason"],"properties":{"available":{"type":"boolean"},"reason":{"type":"string","enum":["","disabled","platform_subdomain","unsupported_tld","reserved"],"description":"Empty when available. `disabled`: managed DNS is off on this deployment. `platform_subdomain`: the name belongs to a hosting platform (someone.github.io), so its nameservers can't be changed. `unsupported_tld`: there is no registrable domain whose nameservers a registrar can change. `reserved`: CustomDomain™'s own domain."}}},"ManagedDNSRecord":{"type":"object","required":["id","type","name","value","ttl","priority","source"],"properties":{"id":{"type":"string","description":"Stable id derived from the record content.","examples":["mdr_1f3a9c0b7d2e5a4c6b8d"]},"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","SRV","CAA","NS"]},"name":{"type":"string","description":"Fully qualified owner name, lower case (\"acme.com\" is the apex, \"*.acme.com\" a wildcard)."},"value":{"type":"string","description":"A/AAAA: the address. CNAME/NS/MX: the target host (\".\" for a null MX). TXT: the text. SRV: \" \". CAA: ` \"\"`."},"ttl":{"type":"integer","description":"Seconds."},"priority":{"type":["integer","null"],"description":"MX preference or SRV priority; null for other types."},"source":{"type":"string","enum":["discovered","imported","customdomain","manual"],"description":"Where the record came from. `customdomain` records are the ones CustomDomain™ needs for connected domains; they win every conflict and can't be removed here."}}},"ManagedDNSRecordInput":{"type":"object","required":["type","name","value"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","SRV","CAA","NS"]},"name":{"type":"string","description":"Relative to the zone (\"@\", \"www\", \"_dmarc\") or fully qualified inside it."},"value":{"type":"string","description":"Same forms as ManagedDNSRecord.value."},"ttl":{"type":"integer","description":"Seconds; default 3600, clamped to 60 to 604800."},"priority":{"type":["integer","null"],"description":"MX preference (default 10) or SRV priority (default 0)."}}},"ManagedDNSRecordsRequest":{"type":"object","additionalProperties":false,"description":"Exactly one of zone_file or records.","properties":{"zone_file":{"type":"string","maxLength":262144,"description":"A BIND zone file (RFC 1035 master format)."},"records":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/ManagedDNSRecordInput"}}}},"ManagedDNSView":{"type":"object","required":["zone","status","nameservers","observed_nameservers","registrar","records","warnings","checked_at","activated_at"],"properties":{"zone":{"type":"string","description":"The hosted zone: the registrable domain.","examples":["acme.com"]},"status":{"type":"string","enum":["awaiting_delegation","active","failed"],"description":"`awaiting_delegation`: the zone holds the records; set the nameservers below at the registrar. `active`: every nameserver the registry lists is ours. `failed`: the switch never happened within 14 days, or the nameservers moved away again (the first warning says which); a failed zone keeps being checked and turns active once the delegation appears."},"nameservers":{"type":"array","items":{"type":"string"},"description":"The nameservers to set at the registrar."},"observed_nameservers":{"type":"array","items":{"type":"string"},"description":"The nameservers the registry listed at the last check."},"registrar":{"description":"The domain's registrar from RDAP, or null when unknown.","oneOf":[{"type":"object","required":["name","url"],"properties":{"name":{"type":"string"},"url":{"type":"string","description":"The registrar's website, or an empty string."}}},{"type":"null"}]},"records":{"type":"array","items":{"$ref":"#/components/schemas/ManagedDNSRecord"}},"warnings":{"type":"array","items":{"type":"string"},"description":"Plain-language notes for the user (a partial delegation, records a zone file import skipped, records replaced)."},"checked_at":{"type":"string","format":"date-time","description":"When the delegation was last checked."},"activated_at":{"type":["string","null"],"format":"date-time"}}},"AgentScope":{"type":"string","enum":["domains:read","domains:connect","domains:disconnect","domains:purchase"],"description":"What an agent grant may do. `domains:read` looks: availability, connections, records, certificates, diagnoses, orders and the billing standing. `domains:connect` changes: connect a domain, recheck it, reapply its records, start a one click setup. `domains:disconnect` removes a connected domain, and the call must name the domain. `domains:purchase` spends, up to the grant's monthly cap."},"AgentClientRegistration":{"type":"object","required":["client_name","redirect_uris"],"description":"RFC 7591 client metadata. Anything else a client sends (`client_uri`, `logo_uri`, `scope`, `contacts` and so on) is accepted and ignored.","properties":{"client_name":{"type":"string","maxLength":100,"description":"Shown to the person who approves the agent. At most 100 characters, with no control or invisible characters and no Latin letters mixed with look-alike letters from another alphabet. A name that claims a well known brand is refused unless every redirect host belongs to that brand or is a loopback address."},"redirect_uris":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","format":"uri","maxLength":2000},"description":"Where the authorization code may be sent. `https`, or `http` on a loopback host (`localhost`, `127.0.0.1`, `::1`) for a program on the person's own computer. No fragment and no user information. A redirect URI is matched exactly later, except for the port of a loopback one."},"grant_types":{"type":"array","items":{"type":"string"},"description":"Optional. When sent it must include `authorization_code`; other values are ignored. The client is registered for `authorization_code` and `refresh_token`."},"response_types":{"type":"array","items":{"type":"string"},"description":"Optional. When sent it must include `code`."},"token_endpoint_auth_method":{"type":"string","description":"Ignored. Every agent client is a public client (`none`) and PKCE protects its code."}}},"AgentClient":{"type":"object","required":["client_id","client_id_issued_at","client_name","redirect_uris","token_endpoint_auth_method","grant_types","response_types"],"properties":{"client_id":{"type":"string","description":"Starts with `agc_`."},"client_id_issued_at":{"type":"integer","format":"int64","description":"Unix time of the registration."},"client_name":{"type":"string"},"redirect_uris":{"type":"array","items":{"type":"string"},"description":"The registered URIs, normalized."},"token_endpoint_auth_method":{"type":"string","enum":["none"]},"grant_types":{"type":"array","items":{"type":"string"},"examples":[["authorization_code","refresh_token"]]},"response_types":{"type":"array","items":{"type":"string"},"examples":[["code"]]}}},"OAuthError":{"type":"object","required":["error"],"description":"The RFC 6749 and RFC 7591 error envelope the token, revoke and register endpoints answer with (the `{code, title, details}` envelope of the rest of the API is not used there).","properties":{"error":{"type":"string","description":"`invalid_request`, `invalid_grant`, `invalid_target`, `unsupported_grant_type`, `invalid_client_metadata`, `invalid_redirect_uri`, `server_error` or `temporarily_unavailable`."},"error_description":{"type":"string"}}},"AgentTokenRequest":{"type":"object","required":["grant_type","client_id"],"properties":{"grant_type":{"type":"string","enum":["authorization_code","refresh_token"]},"client_id":{"type":"string"},"code":{"type":"string","description":"With `authorization_code`: the single use code from the redirect. It lives 5 minutes. Presenting a code that already issued tokens is `invalid_grant` and revokes the grant they came from (RFC 6749 §4.1.2)."},"code_verifier":{"type":"string","description":"With `authorization_code`: the PKCE verifier for the `code_challenge` sent to authorize."},"redirect_uri":{"type":"string","format":"uri","description":"With `authorization_code`: exactly the `redirect_uri` sent to authorize."},"refresh_token":{"type":"string","description":"With `refresh_token`: the latest refresh token. It is good for one exchange."},"resource":{"description":"RFC 8707. The resource the token is for. With `authorization_code` it must be the one the person approved; with `refresh_token` it picks the audience of the new access token (the MCP endpoint when omitted). In a form body repeat the field; in JSON send a string or a list.","oneOf":[{"type":"string","format":"uri"},{"type":"array","items":{"type":"string","format":"uri"}}]}}},"AgentTokenResponse":{"type":"object","required":["access_token","token_type","expires_in"],"properties":{"access_token":{"type":"string","description":"An ES256 JWT. Verify it against `/.well-known/jwks.json`."},"token_type":{"type":"string","enum":["Bearer"]},"expires_in":{"type":"integer","description":"Seconds the access token lives (900)."},"refresh_token":{"type":"string","description":"A new refresh token. The one just used no longer works."},"scope":{"type":"string","description":"The scopes the grant carries, separated by spaces."}}},"AgentConsentRequest":{"type":"object","required":["client_id","client_name","redirect_uri","scopes","redirect_host","verified","local","registration"],"properties":{"client_id":{"type":"string"},"client_name":{"type":"string"},"redirect_uri":{"type":"string","description":"Where the authorization code goes if the person approves."},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/AgentScope"},"description":"What the agent asked for."},"state":{"type":"string","description":"The agent's own state value, echoed back to it."},"redirect_host":{"type":"string","description":"The host of `redirect_uri`. The client cannot choose it freely the way it chooses its name, so show it."},"verified":{"type":"boolean","description":"True when `redirect_host` is a known assistant's own callback host or a loopback address, and the name imitates no brand."},"verified_as":{"type":"string","description":"The known assistant `redirect_host` belongs to."},"local":{"type":"boolean","description":"True when the code goes to a program on the approver's own computer (a loopback redirect)."},"imitates":{"type":"string","description":"The brand the name claims without owning the redirect host. Such a request cannot be approved."},"registration":{"type":"string","enum":["dynamic","metadata_document"],"description":"How the client identified itself, by RFC 7591 registration or by a Client ID Metadata Document."},"registered_at":{"type":"string","format":"date-time","description":"When a dynamically registered client registered."},"client_id_host":{"type":"string","description":"The host that publishes a metadata document client's document."}}},"AgentConsentApproval":{"type":"object","required":["request","application_id","scopes"],"description":"The body is decoded with unknown fields rejected.","properties":{"request":{"type":"string","description":"The consent request id the browser arrived with (`aqr_...`)."},"member_id":{"type":"string","description":"The member who approves, recorded as the grant's approver, the email recipient and the audit actor. It must belong to the workspace. With a member's own key it must be that member (`403` otherwise) and may be left out; with any other key it is required."},"application_id":{"type":"string","description":"The one application of the workspace the agent will act within."},"scopes":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/AgentScope"},"description":"What is approved, a subset of what the agent asked for."},"can_purchase":{"type":"boolean","deprecated":true,"description":"Ignored. Purchase is allowed exactly when `domains:purchase` is among the scopes."},"spend_cap_cents":{"type":"integer","minimum":0,"description":"The monthly spend cap in US cents. Required, and above 0, with `domains:purchase`, which also needs a saved card (`409` without one)."},"persist":{"type":"boolean","default":true,"description":"True (the default) keeps the access until it is revoked. False ends it after `expires_days`."},"expires_days":{"type":"integer","minimum":0,"default":30,"description":"With `persist: false`, days until the grant expires."},"acknowledged_unverified":{"type":"boolean","default":false,"description":"The approver confirmed they recognize the host the authorization code goes to. Required (`true`) when that host is neither a known assistant's (`verified`) nor a loopback address (`local`) in `GET /agent/consent-request/{id}`; without it such a consent is refused with `400`."}}},"AgentConsentResult":{"type":"object","required":["redirect_uri","code","grant_id"],"properties":{"redirect_uri":{"type":"string","description":"Where to send the person: the agent's redirect URI with `code` and `state` added."},"code":{"type":"string","description":"The single use authorization code. It lives 5 minutes."},"state":{"type":"string"},"grant_id":{"type":"string"}}},"AgentGrant":{"type":"object","required":["id","tenant_id","agent_client_id","agent_name","scopes","can_purchase","spend_cap_cents","created_at","spend_this_period_cents","period"],"properties":{"id":{"type":"string","description":"Starts with `grt_`."},"tenant_id":{"type":"string"},"agent_client_id":{"type":"string"},"application_id":{"type":"string","description":"The application the grant is bound to."},"authorized_by":{"type":"string","description":"The member who approved it."},"agent_name":{"type":"string"},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/AgentScope"}},"can_purchase":{"type":"boolean","description":"True when the grant carries `domains:purchase`."},"spend_cap_cents":{"type":"integer","description":"The monthly spend cap in US cents (0 without purchase access)."},"expires_at":{"type":"string","format":"date-time","description":"Absent for persistent access."},"created_at":{"type":"string","format":"date-time"},"revoked_at":{"type":"string","format":"date-time","description":"Present once the access was ended."},"spend_this_period_cents":{"type":"integer","description":"Spent against the cap this month."},"period":{"type":"string","description":"The month `spend_this_period_cents` counts, `YYYY-MM` (UTC)."}}},"AgentGrantList":{"type":"object","required":["grants"],"properties":{"grants":{"type":"array","items":{"$ref":"#/components/schemas/AgentGrant"}}}}}}}},"proxyUrl":"$undefined"},"document":"./openapi-v1.yaml","operations":[{"path":"/templates","method":"get"}],"showDescription":true}]

List one-click setup service templates

Response Body

200

503application/json

`application/json`