@rathnasgala2/schemas 3.4.0 → 3.5.0

package/openapi/openapi.yaml

@@ -1256,6 +1256,174 @@ components:
         - RECONCILING
         - INCONCLUSIVE
       type: string
+    DnsConnection:
+      additionalProperties: false
+      description: One attempt to add or remove a domain's DNS records at the person's DNS provider (SCHEMA-3.5.0). `outcome` is present when `phase` is `CANCELLED`, `FAILED` or `EXPIRED`; `plan` when `NEEDS_CONFIRMATION` or `APPLIED`; `applied` when `APPLIED`. The provider's access is used within one request chain (or held encrypted for at most `expiresAt` on `NEEDS_CONFIRMATION`) and revoked afterwards; Galascribe keeps none.
+      properties:
+        applied:
+          additionalProperties: false
+          properties:
+            at:
+              $ref: "#/components/schemas/PortableProblemRfc3339"
+            created:
+              minimum: 0
+              type: integer
+            deleted:
+              minimum: 0
+              type: integer
+            replaced:
+              minimum: 0
+              type: integer
+          required:
+            - at
+            - created
+            - replaced
+            - deleted
+          type: object
+        connectionId:
+          format: uuid
+          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+          type: string
+        createdAt:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+        expiresAt:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+        intent:
+          $ref: "#/components/schemas/DnsIntent"
+        outcome:
+          additionalProperties: false
+          properties:
+            code:
+              $ref: "#/components/schemas/DnsConnectionOutcomeCode"
+            detail:
+              maxLength: 500
+              minLength: 1
+              type: string
+          required:
+            - code
+            - detail
+          type: object
+        phase:
+          $ref: "#/components/schemas/DnsConnectionPhase"
+        plan:
+          items:
+            $ref: "#/components/schemas/DnsPlanEntry"
+          maxItems: 32
+          minItems: 0
+          type: array
+        provider:
+          $ref: "#/components/schemas/DnsProvider"
+        zone:
+          additionalProperties: false
+          properties:
+            accountName:
+              maxLength: 255
+              minLength: 1
+              type: string
+            name:
+              maxLength: 253
+              minLength: 1
+              type: string
+          required:
+            - name
+            - accountName
+          type: object
+      required:
+        - connectionId
+        - provider
+        - intent
+        - phase
+        - createdAt
+        - expiresAt
+      type: object
+    DnsConnectionOutcomeCode:
+      description: "Why a connection ended without success: `CANCELLED` (consent denied or plan discarded); `ZONE_NOT_FOUND` (the domain is not in the provider account chosen); `ZONE_AMBIGUOUS` (more than one active zone of that name across the accounts granted); `SCOPE_DECLINED` (the person did not grant what was needed); `PROVIDER_FAILED` (the provider failed or refused); `STATE_INVALID` (the return from the provider could not be matched to this connection); `EXPIRED`."
+      enum:
+        - CANCELLED
+        - ZONE_NOT_FOUND
+        - ZONE_AMBIGUOUS
+        - SCOPE_DECLINED
+        - PROVIDER_FAILED
+        - STATE_INVALID
+        - EXPIRED
+      type: string
+    DnsConnectionPhase:
+      description: "`STARTED` (waiting for the person at the provider); `NEEDS_CONFIRMATION` (something would be replaced, nothing touched yet); `APPLIED`; `CANCELLED` (the person declined, or discarded the plan); `FAILED`; `EXPIRED` (the person did not finish in time)."
+      enum:
+        - STARTED
+        - NEEDS_CONFIRMATION
+        - APPLIED
+        - CANCELLED
+        - FAILED
+        - EXPIRED
+      type: string
+    DnsIntent:
+      description: "`ADD` writes the domain's records at the provider; `REMOVE` deletes only the records whose values are Galascribe's targets, never anything else at that name."
+      enum:
+        - ADD
+        - REMOVE
+      type: string
+    DnsPlanAction:
+      description: "`CREATE` a record that is not there; `KEEP` one already identical; `REPLACE` one of the same type, or a CNAME where an A/AAAA must go (or the reverse), that differs; `DELETE` a record carrying a Galascribe target value (`REMOVE` only)."
+      enum:
+        - CREATE
+        - KEEP
+        - REPLACE
+        - DELETE
+      type: string
+    DnsPlanEntry:
+      additionalProperties: false
+      description: "One record in a connection's plan. `record` is what Galascribe wants at that name; `existing` is what the provider has there now (absent for `CREATE`). Records are always written DNS-only (`proxied: false`) so GitHub can issue the certificate."
+      properties:
+        action:
+          $ref: "#/components/schemas/DnsPlanAction"
+        existing:
+          additionalProperties: false
+          properties:
+            proxied:
+              type: boolean
+            type:
+              maxLength: 16
+              minLength: 1
+              pattern: ^[A-Z][A-Z0-9]*$
+              type: string
+            value:
+              maxLength: 4096
+              minLength: 1
+              type: string
+          required:
+            - type
+            - value
+            - proxied
+          type: object
+        record:
+          $ref: "#/components/schemas/DomainDnsRecord"
+      required:
+        - action
+        - record
+      type: object
+    DnsProvider:
+      description: Where a domain's DNS records live. `CLOUDFLARE` today; a further provider is an additive value.
+      enum:
+        - CLOUDFLARE
+      type: string
+    DnsProviderOffer:
+      additionalProperties: false
+      description: A provider this environment can connect to for this binding, and what it can do now.
+      properties:
+        intents:
+          items:
+            $ref: "#/components/schemas/DnsIntent"
+          maxItems: 2
+          minItems: 1
+          type: array
+          uniqueItems: true
+        provider:
+          $ref: "#/components/schemas/DnsProvider"
+      required:
+        - provider
+        - intents
+      type: object
     DomainBinding:
       additionalProperties: false
       description: A custom domain on GitHub Pages for one publication (SCHEMA-3.3.0). `dns.records` are exactly the records to add at the registrar (a CNAME to `<owner>.github.io` for a subdomain; GitHub's four A and four AAAA records for an apex). Galascribe checks DNS before it sets the Pages custom domain, then waits for GitHub's certificate and routing; `ACTIVE` proposes the change that moves `canonicalBase` to the domain, and the site moves at the next publish. `expiresAt` is set while `OWNERSHIP_PENDING` (7 days).
@@ -1271,6 +1439,13 @@ components:
           properties:
             observed:
               $ref: "#/components/schemas/DomainDnsObservation"
+            providers:
+              description: The DNS providers Galascribe can connect to for this binding right now (SCHEMA-3.5.0). Present only when the provider is configured in this environment and the binding's state has records to add, or (`REMOVE`) to remove. A client shows a connect button exactly when this names the provider and intent; it never decides from `nextStep`.
+              items:
+                $ref: "#/components/schemas/DnsProviderOffer"
+              maxItems: 4
+              minItems: 0
+              type: array
             records:
               items:
                 $ref: "#/components/schemas/DomainDnsRecord"
@@ -2340,6 +2515,9 @@ components:
         - version
         - state
       type: object
+    GetOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdResponse:
+      allOf:
+        - $ref: "#/components/schemas/DnsConnection"
     GetOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdResponse:
       allOf:
         - $ref: "#/components/schemas/DomainBinding"
@@ -12450,6 +12628,44 @@ components:
     PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDetachResponse:
       allOf:
         - $ref: "#/components/schemas/DomainBinding"
+    PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdApplyResponse:
+      allOf:
+        - $ref: "#/components/schemas/DnsConnection"
+    PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdDiscardResponse:
+      allOf:
+        - $ref: "#/components/schemas/DnsConnection"
+    PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsRequest:
+      additionalProperties: false
+      properties:
+        intent:
+          $ref: "#/components/schemas/DnsIntent"
+        provider:
+          $ref: "#/components/schemas/DnsProvider"
+      required:
+        - provider
+        - intent
+      type: object
+    PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsResponse:
+      additionalProperties: false
+      properties:
+        authorizationUrl:
+          description: The provider's consent address. A client navigates to it only when it is an `https` address on the provider's own host.
+          format: uri
+          maxLength: 4096
+          minLength: 1
+          pattern: ^https://[^\s]+$
+          type: string
+        connectionId:
+          format: uuid
+          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+          type: string
+        expiresAt:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+      required:
+        - connectionId
+        - authorizationUrl
+        - expiresAt
+      type: object
     PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsRequest:
       additionalProperties: false
       properties:
@@ -16791,6 +17007,77 @@ paths:
         - NONE
       x-gala-success-category: protocol
       x-gala-tenant-scope: NONE
+  /v2/callbacks/cloudflare/oauth:
+    get:
+      description: |
+        The address Cloudflare sends the person back to after the consent screen. It never answers with a problem document for what the provider sends: every outcome, including a denied consent or an unknown `state`, is a `303` to the Domain page with `?dns=<connectionId>` (or without it when the connection cannot be identified), and `GET .../dns-connections/{connectionId}` says what happened. `code`, `state`, `error` and `iss` are never logged or echoed. Only a value longer than its limit is refused as `400 VALIDATION_FAILED`, before any connection is touched.
+      operationId: getCallbacksCloudflareOauth
+      parameters:
+        - $ref: "#/components/parameters/XCorrelationId"
+        - example: example
+          in: query
+          name: code
+          required: false
+          schema:
+            maxLength: 8192
+            minLength: 1
+            type: string
+        - example: example
+          in: query
+          name: state
+          required: false
+          schema:
+            maxLength: 8192
+            minLength: 1
+            type: string
+        - example: example
+          in: query
+          name: error
+          required: false
+          schema:
+            maxLength: 512
+            minLength: 1
+            type: string
+        - example: example
+          in: query
+          name: iss
+          required: false
+          schema:
+            maxLength: 2048
+            minLength: 1
+            type: string
+      responses:
+        "303":
+          description: consume the exact Cloudflare OAuth callback transaction succeeded
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            Location:
+              $ref: "#/components/headers/Location"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+        "400":
+          $ref: "#/components/responses/ValidationFailed"
+      security: []
+      summary: consume the exact Cloudflare OAuth callback transaction
+      tags:
+        - callbacks
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-capability-key: null
+      x-gala-concurrency: single-use-transaction
+      x-gala-conditional-capabilities: []
+      x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
+      x-gala-nullability: required-and-nullable-are-explicit
+      x-gala-purpose: consume the exact Cloudflare OAuth callback transaction
+      x-gala-reachable-problems:
+        - VALIDATION_FAILED
+      x-gala-replay-identity: oauth-state
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: oauth-callback
+      x-gala-tenant-scope: NONE
   /v2/callbacks/github/app:
     post:
       operationId: postCallbacksGithubApp
@@ -32122,6 +32409,1164 @@ paths:
         - NONE
       x-gala-success-category: query
       x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
+  /v2/organizations/{organizationId}/publications/{publicationId}/domains/{domainId}/dns-connections:
+    post:
+      description: |
+        Starts a connection to the person's DNS provider so Galascribe can add (`ADD`) or remove (`REMOVE`) the domain's DNS records there, and returns the provider's consent address (`authorizationUrl`); the App navigates the whole page to it. The provider sends the person back to the Domain page, where `GET .../dns-connections/{connectionId}` says what happened. Only offered when `dns.providers` on the binding lists the provider and the intent. `409 DNS_CONNECTION_NOT_APPLICABLE` when the binding's state has no records to add or remove; `503 DNS_PROVIDER_NOT_CONFIGURED` when this environment has no connection to that provider; `429 RATE_LIMITED` after one start per domain per minute. The connection is valid until `expiresAt`.
+      operationId: postOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnections
+      parameters:
+        - $ref: "#/components/parameters/XCorrelationId"
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: organizationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: publicationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: domainId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - $ref: "#/components/parameters/IdempotencyKey"
+        - $ref: "#/components/parameters/XCsrfToken"
+      requestBody:
+        content:
+          application/json:
+            examples:
+              nominal:
+                summary: Nominal valid request
+                value:
+                  intent: ADD
+                  provider: CLOUDFLARE
+            schema:
+              $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsRequest"
+        required: true
+      responses:
+        "201":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    authorizationUrl: https://dash.cloudflare.com/oauth2/auth?client_id=example&response_type=code&state=example
+                    connectionId: 018f0000-0000-7000-8000-000000000001
+                    expiresAt: "2026-10-10T12:10:00.000Z"
+              schema:
+                $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsResponse"
+          description: start adding (or removing) a domain's DNS records at the person's DNS provider succeeded
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            Location:
+              $ref: "#/components/headers/Location"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+        "400":
+          content:
+            application/problem+json:
+              examples:
+                REQUEST_FIELD_UNKNOWN:
+                  summary: REQUEST_FIELD_UNKNOWN
+                  value:
+                    code: REQUEST_FIELD_UNKNOWN
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 400
+                    title: REQUEST_FIELD_UNKNOWN
+                    type: urn:gala:problem:request-field-unknown
+                VALIDATION_FAILED:
+                  summary: VALIDATION_FAILED
+                  value:
+                    code: VALIDATION_FAILED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 400
+                    title: VALIDATION_FAILED
+                    type: urn:gala:problem:validation-failed
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: REQUEST_FIELD_UNKNOWN, VALIDATION_FAILED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - REQUEST_FIELD_UNKNOWN
+            - VALIDATION_FAILED
+        "401":
+          content:
+            application/problem+json:
+              examples:
+                AUTHENTICATION_REQUIRED:
+                  summary: AUTHENTICATION_REQUIRED
+                  value:
+                    code: AUTHENTICATION_REQUIRED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 401
+                    title: AUTHENTICATION_REQUIRED
+                    type: urn:gala:problem:authentication-required
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHENTICATION_REQUIRED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHENTICATION_REQUIRED
+        "403":
+          content:
+            application/problem+json:
+              examples:
+                AUTHORIZATION_DENIED:
+                  summary: AUTHORIZATION_DENIED
+                  value:
+                    code: AUTHORIZATION_DENIED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 403
+                    title: AUTHORIZATION_DENIED
+                    type: urn:gala:problem:authorization-denied
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHORIZATION_DENIED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHORIZATION_DENIED
+        "404":
+          content:
+            application/problem+json:
+              examples:
+                RESOURCE_NOT_FOUND:
+                  summary: RESOURCE_NOT_FOUND
+                  value:
+                    code: RESOURCE_NOT_FOUND
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 404
+                    title: RESOURCE_NOT_FOUND
+                    type: urn:gala:problem:resource-not-found
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: RESOURCE_NOT_FOUND
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - RESOURCE_NOT_FOUND
+        "409":
+          content:
+            application/problem+json:
+              examples:
+                COMMAND_REPLAY_CONFLICT:
+                  summary: COMMAND_REPLAY_CONFLICT
+                  value:
+                    code: COMMAND_REPLAY_CONFLICT
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: COMMAND_REPLAY_CONFLICT
+                    type: urn:gala:problem:command-replay-conflict
+                DNS_CONNECTION_NOT_APPLICABLE:
+                  summary: DNS_CONNECTION_NOT_APPLICABLE
+                  value:
+                    code: DNS_CONNECTION_NOT_APPLICABLE
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: DNS_CONNECTION_NOT_APPLICABLE
+                    type: urn:gala:problem:dns-connection-not-applicable
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: COMMAND_REPLAY_CONFLICT, DNS_CONNECTION_NOT_APPLICABLE
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - COMMAND_REPLAY_CONFLICT
+            - DNS_CONNECTION_NOT_APPLICABLE
+        "429":
+          content:
+            application/problem+json:
+              examples:
+                RATE_LIMITED:
+                  summary: RATE_LIMITED
+                  value:
+                    code: RATE_LIMITED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: true
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 429
+                    title: RATE_LIMITED
+                    type: urn:gala:problem:rate-limited
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: RATE_LIMITED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            Retry-After:
+              $ref: "#/components/headers/RetryAfter"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - RATE_LIMITED
+        "503":
+          content:
+            application/problem+json:
+              examples:
+                DNS_PROVIDER_NOT_CONFIGURED:
+                  summary: DNS_PROVIDER_NOT_CONFIGURED
+                  value:
+                    code: DNS_PROVIDER_NOT_CONFIGURED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 503
+                    title: DNS_PROVIDER_NOT_CONFIGURED
+                    type: urn:gala:problem:dns-provider-not-configured
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: DNS_PROVIDER_NOT_CONFIGURED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - DNS_PROVIDER_NOT_CONFIGURED
+      security:
+        - browserSession: []
+      summary: start adding (or removing) a domain's DNS records at the person's DNS provider
+      tags:
+        - domains
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-capability-key: publication.settings.manage
+      x-gala-concurrency: domain-binding-version
+      x-gala-conditional-capabilities: []
+      x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
+      x-gala-nullability: required-and-nullable-are-explicit
+      x-gala-purpose: start adding (or removing) a domain's DNS records at the person's DNS provider
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - AUTHORIZATION_DENIED
+        - COMMAND_REPLAY_CONFLICT
+        - DNS_CONNECTION_NOT_APPLICABLE
+        - DNS_PROVIDER_NOT_CONFIGURED
+        - RATE_LIMITED
+        - REQUEST_FIELD_UNKNOWN
+        - RESOURCE_NOT_FOUND
+        - VALIDATION_FAILED
+      x-gala-replay-identity: idempotency-key
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: create
+      x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
+  /v2/organizations/{organizationId}/publications/{publicationId}/domains/{domainId}/dns-connections/{connectionId}:
+    get:
+      description: |
+        One DNS connection of this domain: where it stands (`phase`), what it will or did change (`plan`, `applied`) and, when it ended without success, why (`outcome`). `NEEDS_CONFIRMATION` means something at the provider would be replaced and nothing has been touched yet: `:apply` writes the plan, `:discard` leaves everything as it was. `404 DNS_CONNECTION_NOT_FOUND` for an unknown connection.
+      operationId: getOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionId
+      parameters:
+        - $ref: "#/components/parameters/XCorrelationId"
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: organizationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: publicationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: domainId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: connectionId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    connectionId: 018f0000-0000-7000-8000-000000000001
+                    createdAt: "2026-10-10T12:00:00.000Z"
+                    expiresAt: "2026-10-10T12:10:00.000Z"
+                    intent: ADD
+                    phase: NEEDS_CONFIRMATION
+                    plan:
+                      - action: REPLACE
+                        existing:
+                          proxied: true
+                          type: A
+                          value: 203.0.113.7
+                        record:
+                          name: "@"
+                          type: A
+                          value: 185.199.108.153
+                      - action: KEEP
+                        existing:
+                          proxied: false
+                          type: A
+                          value: 185.199.109.153
+                        record:
+                          name: "@"
+                          type: A
+                          value: 185.199.109.153
+                    provider: CLOUDFLARE
+                    zone:
+                      accountName: Maya Personal
+                      name: maya.dev
+              schema:
+                $ref: "#/components/schemas/GetOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdResponse"
+          description: read a DNS connection succeeded
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+        "400":
+          content:
+            application/problem+json:
+              examples:
+                VALIDATION_FAILED:
+                  summary: VALIDATION_FAILED
+                  value:
+                    code: VALIDATION_FAILED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 400
+                    title: VALIDATION_FAILED
+                    type: urn:gala:problem:validation-failed
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: VALIDATION_FAILED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - VALIDATION_FAILED
+        "401":
+          content:
+            application/problem+json:
+              examples:
+                AUTHENTICATION_REQUIRED:
+                  summary: AUTHENTICATION_REQUIRED
+                  value:
+                    code: AUTHENTICATION_REQUIRED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 401
+                    title: AUTHENTICATION_REQUIRED
+                    type: urn:gala:problem:authentication-required
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHENTICATION_REQUIRED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHENTICATION_REQUIRED
+        "403":
+          content:
+            application/problem+json:
+              examples:
+                AUTHORIZATION_DENIED:
+                  summary: AUTHORIZATION_DENIED
+                  value:
+                    code: AUTHORIZATION_DENIED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 403
+                    title: AUTHORIZATION_DENIED
+                    type: urn:gala:problem:authorization-denied
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHORIZATION_DENIED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHORIZATION_DENIED
+        "404":
+          content:
+            application/problem+json:
+              examples:
+                DNS_CONNECTION_NOT_FOUND:
+                  summary: DNS_CONNECTION_NOT_FOUND
+                  value:
+                    code: DNS_CONNECTION_NOT_FOUND
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 404
+                    title: DNS_CONNECTION_NOT_FOUND
+                    type: urn:gala:problem:dns-connection-not-found
+                RESOURCE_NOT_FOUND:
+                  summary: RESOURCE_NOT_FOUND
+                  value:
+                    code: RESOURCE_NOT_FOUND
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 404
+                    title: RESOURCE_NOT_FOUND
+                    type: urn:gala:problem:resource-not-found
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: DNS_CONNECTION_NOT_FOUND, RESOURCE_NOT_FOUND
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - DNS_CONNECTION_NOT_FOUND
+            - RESOURCE_NOT_FOUND
+      security:
+        - browserSession: []
+      summary: read a DNS connection
+      tags:
+        - domains
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-capability-key: publication.view
+      x-gala-concurrency: domain-binding-version
+      x-gala-conditional-capabilities: []
+      x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
+      x-gala-nullability: required-and-nullable-are-explicit
+      x-gala-purpose: read a DNS connection
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - AUTHORIZATION_DENIED
+        - DNS_CONNECTION_NOT_FOUND
+        - RESOURCE_NOT_FOUND
+        - VALIDATION_FAILED
+      x-gala-replay-identity: safe-query
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: query
+      x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
+  /v2/organizations/{organizationId}/publications/{publicationId}/domains/{domainId}/dns-connections/{connectionId}:apply:
+    post:
+      description: |
+        Writes the records in the connection's `plan` at the provider, ends the provider's access, runs the domain's DNS check, and returns the connection as `APPLIED`. `409 DNS_CONNECTION_NOT_CONFIRMABLE` unless the connection is `NEEDS_CONFIRMATION`; `410 DNS_CONNECTION_EXPIRED` when the held access has lapsed (the connection is then `EXPIRED`); `502 DNS_PROVIDER_REJECTED` when the provider refused the change (nothing is half-applied).
+      operationId: postOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdApply
+      parameters:
+        - $ref: "#/components/parameters/XCorrelationId"
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: organizationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: publicationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: domainId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: connectionId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - $ref: "#/components/parameters/IdempotencyKey"
+        - $ref: "#/components/parameters/XCsrfToken"
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    applied:
+                      at: "2026-10-10T12:03:00.000Z"
+                      created: 0
+                      deleted: 0
+                      replaced: 1
+                    connectionId: 018f0000-0000-7000-8000-000000000001
+                    createdAt: "2026-10-10T12:00:00.000Z"
+                    expiresAt: "2026-10-10T12:10:00.000Z"
+                    intent: ADD
+                    phase: APPLIED
+                    plan:
+                      - action: REPLACE
+                        existing:
+                          proxied: true
+                          type: A
+                          value: 203.0.113.7
+                        record:
+                          name: "@"
+                          type: A
+                          value: 185.199.108.153
+                      - action: KEEP
+                        existing:
+                          proxied: false
+                          type: A
+                          value: 185.199.109.153
+                        record:
+                          name: "@"
+                          type: A
+                          value: 185.199.109.153
+                    provider: CLOUDFLARE
+                    zone:
+                      accountName: Maya Personal
+                      name: maya.dev
+              schema:
+                $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdApplyResponse"
+          description: apply the DNS changes a connection is waiting to make succeeded
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+        "400":
+          content:
+            application/problem+json:
+              examples:
+                VALIDATION_FAILED:
+                  summary: VALIDATION_FAILED
+                  value:
+                    code: VALIDATION_FAILED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 400
+                    title: VALIDATION_FAILED
+                    type: urn:gala:problem:validation-failed
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: VALIDATION_FAILED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - VALIDATION_FAILED
+        "401":
+          content:
+            application/problem+json:
+              examples:
+                AUTHENTICATION_REQUIRED:
+                  summary: AUTHENTICATION_REQUIRED
+                  value:
+                    code: AUTHENTICATION_REQUIRED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 401
+                    title: AUTHENTICATION_REQUIRED
+                    type: urn:gala:problem:authentication-required
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHENTICATION_REQUIRED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHENTICATION_REQUIRED
+        "403":
+          content:
+            application/problem+json:
+              examples:
+                AUTHORIZATION_DENIED:
+                  summary: AUTHORIZATION_DENIED
+                  value:
+                    code: AUTHORIZATION_DENIED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 403
+                    title: AUTHORIZATION_DENIED
+                    type: urn:gala:problem:authorization-denied
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHORIZATION_DENIED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHORIZATION_DENIED
+        "404":
+          content:
+            application/problem+json:
+              examples:
+                DNS_CONNECTION_NOT_FOUND:
+                  summary: DNS_CONNECTION_NOT_FOUND
+                  value:
+                    code: DNS_CONNECTION_NOT_FOUND
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 404
+                    title: DNS_CONNECTION_NOT_FOUND
+                    type: urn:gala:problem:dns-connection-not-found
+                RESOURCE_NOT_FOUND:
+                  summary: RESOURCE_NOT_FOUND
+                  value:
+                    code: RESOURCE_NOT_FOUND
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 404
+                    title: RESOURCE_NOT_FOUND
+                    type: urn:gala:problem:resource-not-found
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: DNS_CONNECTION_NOT_FOUND, RESOURCE_NOT_FOUND
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - DNS_CONNECTION_NOT_FOUND
+            - RESOURCE_NOT_FOUND
+        "409":
+          content:
+            application/problem+json:
+              examples:
+                COMMAND_REPLAY_CONFLICT:
+                  summary: COMMAND_REPLAY_CONFLICT
+                  value:
+                    code: COMMAND_REPLAY_CONFLICT
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: COMMAND_REPLAY_CONFLICT
+                    type: urn:gala:problem:command-replay-conflict
+                DNS_CONNECTION_NOT_CONFIRMABLE:
+                  summary: DNS_CONNECTION_NOT_CONFIRMABLE
+                  value:
+                    code: DNS_CONNECTION_NOT_CONFIRMABLE
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: DNS_CONNECTION_NOT_CONFIRMABLE
+                    type: urn:gala:problem:dns-connection-not-confirmable
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: COMMAND_REPLAY_CONFLICT, DNS_CONNECTION_NOT_CONFIRMABLE
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - COMMAND_REPLAY_CONFLICT
+            - DNS_CONNECTION_NOT_CONFIRMABLE
+        "410":
+          content:
+            application/problem+json:
+              examples:
+                DNS_CONNECTION_EXPIRED:
+                  summary: DNS_CONNECTION_EXPIRED
+                  value:
+                    code: DNS_CONNECTION_EXPIRED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 410
+                    title: DNS_CONNECTION_EXPIRED
+                    type: urn:gala:problem:dns-connection-expired
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: DNS_CONNECTION_EXPIRED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - DNS_CONNECTION_EXPIRED
+        "502":
+          content:
+            application/problem+json:
+              examples:
+                DNS_PROVIDER_REJECTED:
+                  summary: DNS_PROVIDER_REJECTED
+                  value:
+                    code: DNS_PROVIDER_REJECTED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: true
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 502
+                    title: DNS_PROVIDER_REJECTED
+                    type: urn:gala:problem:dns-provider-rejected
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: DNS_PROVIDER_REJECTED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - DNS_PROVIDER_REJECTED
+      security:
+        - browserSession: []
+      summary: apply the DNS changes a connection is waiting to make
+      tags:
+        - domains
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-capability-key: publication.settings.manage
+      x-gala-concurrency: domain-binding-version
+      x-gala-conditional-capabilities: []
+      x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
+      x-gala-nullability: required-and-nullable-are-explicit
+      x-gala-purpose: apply the DNS changes a connection is waiting to make
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - AUTHORIZATION_DENIED
+        - COMMAND_REPLAY_CONFLICT
+        - DNS_CONNECTION_EXPIRED
+        - DNS_CONNECTION_NOT_CONFIRMABLE
+        - DNS_CONNECTION_NOT_FOUND
+        - DNS_PROVIDER_REJECTED
+        - RESOURCE_NOT_FOUND
+        - VALIDATION_FAILED
+      x-gala-replay-identity: idempotency-key
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: protocol
+      x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
+  /v2/organizations/{organizationId}/publications/{publicationId}/domains/{domainId}/dns-connections/{connectionId}:discard:
+    post:
+      description: |
+        Ends a connection that is waiting for confirmation without changing anything at the provider, ends the provider's access, and returns the connection as `CANCELLED`. `409 DNS_CONNECTION_NOT_CONFIRMABLE` unless the connection is `NEEDS_CONFIRMATION`.
+      operationId: postOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdDiscard
+      parameters:
+        - $ref: "#/components/parameters/XCorrelationId"
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: organizationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: publicationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: domainId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: connectionId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - $ref: "#/components/parameters/IdempotencyKey"
+        - $ref: "#/components/parameters/XCsrfToken"
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    connectionId: 018f0000-0000-7000-8000-000000000001
+                    createdAt: "2026-10-10T12:00:00.000Z"
+                    expiresAt: "2026-10-10T12:10:00.000Z"
+                    intent: ADD
+                    outcome:
+                      code: CANCELLED
+                      detail: The records were left as they were.
+                    phase: CANCELLED
+                    plan:
+                      - action: REPLACE
+                        existing:
+                          proxied: true
+                          type: A
+                          value: 203.0.113.7
+                        record:
+                          name: "@"
+                          type: A
+                          value: 185.199.108.153
+                      - action: KEEP
+                        existing:
+                          proxied: false
+                          type: A
+                          value: 185.199.109.153
+                        record:
+                          name: "@"
+                          type: A
+                          value: 185.199.109.153
+                    provider: CLOUDFLARE
+                    zone:
+                      accountName: Maya Personal
+                      name: maya.dev
+              schema:
+                $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdDiscardResponse"
+          description: leave the provider's DNS records as they are and end a connection succeeded
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+        "400":
+          content:
+            application/problem+json:
+              examples:
+                VALIDATION_FAILED:
+                  summary: VALIDATION_FAILED
+                  value:
+                    code: VALIDATION_FAILED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 400
+                    title: VALIDATION_FAILED
+                    type: urn:gala:problem:validation-failed
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: VALIDATION_FAILED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - VALIDATION_FAILED
+        "401":
+          content:
+            application/problem+json:
+              examples:
+                AUTHENTICATION_REQUIRED:
+                  summary: AUTHENTICATION_REQUIRED
+                  value:
+                    code: AUTHENTICATION_REQUIRED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 401
+                    title: AUTHENTICATION_REQUIRED
+                    type: urn:gala:problem:authentication-required
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHENTICATION_REQUIRED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHENTICATION_REQUIRED
+        "403":
+          content:
+            application/problem+json:
+              examples:
+                AUTHORIZATION_DENIED:
+                  summary: AUTHORIZATION_DENIED
+                  value:
+                    code: AUTHORIZATION_DENIED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 403
+                    title: AUTHORIZATION_DENIED
+                    type: urn:gala:problem:authorization-denied
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHORIZATION_DENIED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHORIZATION_DENIED
+        "404":
+          content:
+            application/problem+json:
+              examples:
+                DNS_CONNECTION_NOT_FOUND:
+                  summary: DNS_CONNECTION_NOT_FOUND
+                  value:
+                    code: DNS_CONNECTION_NOT_FOUND
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 404
+                    title: DNS_CONNECTION_NOT_FOUND
+                    type: urn:gala:problem:dns-connection-not-found
+                RESOURCE_NOT_FOUND:
+                  summary: RESOURCE_NOT_FOUND
+                  value:
+                    code: RESOURCE_NOT_FOUND
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 404
+                    title: RESOURCE_NOT_FOUND
+                    type: urn:gala:problem:resource-not-found
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: DNS_CONNECTION_NOT_FOUND, RESOURCE_NOT_FOUND
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - DNS_CONNECTION_NOT_FOUND
+            - RESOURCE_NOT_FOUND
+        "409":
+          content:
+            application/problem+json:
+              examples:
+                COMMAND_REPLAY_CONFLICT:
+                  summary: COMMAND_REPLAY_CONFLICT
+                  value:
+                    code: COMMAND_REPLAY_CONFLICT
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: COMMAND_REPLAY_CONFLICT
+                    type: urn:gala:problem:command-replay-conflict
+                DNS_CONNECTION_NOT_CONFIRMABLE:
+                  summary: DNS_CONNECTION_NOT_CONFIRMABLE
+                  value:
+                    code: DNS_CONNECTION_NOT_CONFIRMABLE
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: DNS_CONNECTION_NOT_CONFIRMABLE
+                    type: urn:gala:problem:dns-connection-not-confirmable
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: COMMAND_REPLAY_CONFLICT, DNS_CONNECTION_NOT_CONFIRMABLE
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - COMMAND_REPLAY_CONFLICT
+            - DNS_CONNECTION_NOT_CONFIRMABLE
+      security:
+        - browserSession: []
+      summary: leave the provider's DNS records as they are and end a connection
+      tags:
+        - domains
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-capability-key: publication.settings.manage
+      x-gala-concurrency: domain-binding-version
+      x-gala-conditional-capabilities: []
+      x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
+      x-gala-nullability: required-and-nullable-are-explicit
+      x-gala-purpose: leave the provider's DNS records as they are and end a connection
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - AUTHORIZATION_DENIED
+        - COMMAND_REPLAY_CONFLICT
+        - DNS_CONNECTION_NOT_CONFIRMABLE
+        - DNS_CONNECTION_NOT_FOUND
+        - RESOURCE_NOT_FOUND
+        - VALIDATION_FAILED
+      x-gala-replay-identity: idempotency-key
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: protocol
+      x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
   /v2/organizations/{organizationId}/publications/{publicationId}/domains/{domainId}:check:
     post:
       description: |