@whooshbang/contracts 1.0.0-rc.13

package/openapi/whooshbang-v1.yaml

@@ -0,0 +1,2334 @@
+openapi: 3.1.1
+jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
+# whooshbang:public-origin production api https://api.whooshbang.com
+x-contract-version: 1.0.0-rc.13
+info:
+  title: WhooshBang API
+  version: 1.0.0-rc.13
+  description: |
+    The V1 contract for human account/project administration, project-scoped
+    subscription links, and asynchronous text messages. A Clerk session selects
+    one account for administration. A project credential selects one account,
+    project, and `test` or `live` environment for product operations; request
+    bodies cannot override either authenticated scope.
+
+    A person's OAuth grant selects one account and carries scopes, but no
+    project. It names the project and environment it acts in through the URL
+    path, on the environment-scoped form of each operation; the service checks
+    that path against the granting person's membership on every call. The flat
+    forms remain credential-only and are unchanged.
+
+    Resource identifiers are opaque and are not authorization. Reads outside the
+    credential scope return the same `404` shape as absent resources. Provider
+    credentials, raw Telegram identity, and protected provider responses are
+    never part of this API.
+  termsOfService: https://flowxo.com/terms
+  contact:
+    name: WhooshBang Support
+    url: https://flowxo.com/contact
+  license:
+    name: Proprietary
+    url: https://flowxo.com/terms
+servers:
+  - url: https://api.whooshbang.com
+    description: Environment is selected by the bearer credential, not the URL or body.
+security:
+  - bearerCredential: []
+tags:
+  - name: Account
+    description: The current Clerk organization projected as a WhooshBang account.
+  - name: Projects
+    description: Account-scoped applications with transactionally bootstrapped test/live environments.
+  - name: API credentials
+    description: Human-administered, environment-scoped bearer credentials with one-time secret reveal.
+  - name: Subscription links
+    description: Single-use, expiring Telegram authorization links.
+  - name: Messages
+    description: Asynchronous logical messages and their highest proven outcomes.
+  - name: Machine clients
+    description: Project-administered, destination-bound local-client identities and one-way credential metadata.
+  - name: Machine events
+    description: Durable per-machine long polling and contiguous acknowledgement.
+  - name: Capabilities
+    description: Provider-neutral rendering and evidence capabilities.
+  - name: Customer endpoints
+    description: Verified signed-event destinations with one-time secret lifecycle and content-free diagnostics.
+paths:
+  /v1/account:
+    get:
+      operationId: getAccount
+      summary: Read the current account projection
+      description: |
+        Returns the WhooshBang account selected by the verified Clerk
+        organization session and the caller's projected role. Clerk organization
+        and user identifiers are never public response fields.
+      tags:
+        - Account
+      security:
+        - clerkSession: []
+        - bearerGrant: []
+      x-account-membership: required
+      responses:
+        "200":
+          description: The current account projection.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AccountProjection"
+              examples:
+                projectedAccount:
+                  externalValue: ../fixtures/core-v1/success/account-projection.json
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/projects:
+    get:
+      operationId: listProjects
+      summary: List projects in the current account
+      description: |
+        Returns only projects owned by the account selected by the verified
+        Clerk organization session. Every project includes its complete test/live
+        environment and default-notifier bootstrap.
+      tags:
+        - Projects
+      security:
+        - clerkSession: []
+        - bearerGrant: []
+      x-required-scopes:
+        - projects:read
+      x-account-membership: required
+      parameters:
+        - $ref: "#/components/parameters/ProjectAfterCursor"
+        - $ref: "#/components/parameters/ProjectPageLimit"
+      responses:
+        "200":
+          description: A stable page of projects in the current account.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProjectCollection"
+              examples:
+                projects:
+                  externalValue: ../fixtures/core-v1/success/project-collection.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+    post:
+      operationId: createProject
+      summary: Create a project and its default environments
+      description: |
+        Creates one project inside the authenticated account. The project, its
+        `test` and `live` environments, and one `Default` notifier per
+        environment are one atomic logical resource. Equivalent replay returns
+        the original `201` response without extending idempotency retention.
+      tags:
+        - Projects
+      security:
+        - clerkSession: []
+        - bearerGrant: []
+      x-required-scopes:
+        - projects:write
+      x-account-membership: required
+      x-idempotency:
+        required: true
+        retention_seconds: 604800
+        scope:
+          - authenticated_account
+          - operation_id
+          - key
+        equivalence: validated_request
+        replay_retention_extends: false
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateProjectRequest"
+            examples:
+              createProject:
+                externalValue: ../fixtures/core-v1/requests/create-project.json
+      responses:
+        "201":
+          description: The complete atomic project bootstrap, or the original resource on equivalent replay.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Project"
+              examples:
+                createdProject:
+                  externalValue: ../fixtures/core-v1/success/project-created.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "409":
+          $ref: "#/components/responses/Conflict"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/projects/{project_id}:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+    get:
+      operationId: getProject
+      summary: Read one project in the current account
+      description: |
+        Returns the complete project bootstrap. An absent project and a project
+        outside the authenticated account use the same non-enumerating `404`.
+      tags:
+        - Projects
+      security:
+        - clerkSession: []
+        - bearerGrant: []
+      x-required-scopes:
+        - projects:read
+      x-account-membership: required
+      responses:
+        "200":
+          description: The current project and its two environments.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Project"
+              examples:
+                project:
+                  externalValue: ../fixtures/core-v1/success/project-created.json
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/projects/{project_id}/environments/{environment_id}/credentials:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - $ref: "#/components/parameters/EnvironmentId"
+    get:
+      operationId: listApiCredentials
+      summary: List safe API credential metadata
+      description: |
+        Returns only credentials in the selected project environment owned by
+        the account selected by the verified Clerk organization session.
+        Secrets and digest material are never returned. An absent or
+        out-of-account project or environment uses the same non-enumerating
+        `404`.
+      tags:
+        - API credentials
+      security:
+        - clerkSession: []
+      x-account-membership: required
+      parameters:
+        - $ref: "#/components/parameters/ApiCredentialAfterCursor"
+        - $ref: "#/components/parameters/ApiCredentialPageLimit"
+      responses:
+        "200":
+          description: A stable page of safe credential metadata.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiCredentialCollection"
+              examples:
+                credentials:
+                  externalValue: ../fixtures/core-v1/success/api-credential-collection.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+    post:
+      operationId: createApiCredential
+      summary: Create an environment-scoped API credential
+      description: |
+        Creates one credential in the selected project environment. The complete
+        bearer secret appears only in this creation response. It cannot be read
+        later and is never replayed from an idempotency cache. If a client loses
+        this response, it lists safe metadata and creates then revokes a
+        replacement.
+      tags:
+        - API credentials
+      security:
+        - clerkSession: []
+      x-account-membership: required
+      x-secret-reveal:
+        responses: 1
+        replayable: false
+        later_reads: metadata_only
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateApiCredentialRequest"
+            examples:
+              createCredential:
+                externalValue: ../fixtures/core-v1/requests/create-api-credential.json
+      responses:
+        "201":
+          description: Creation-only secret reveal and safe credential metadata.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiCredentialSecretReveal"
+              examples:
+                createdCredential:
+                  externalValue: ../fixtures/core-v1/success/api-credential-created.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/projects/{project_id}/environments/{environment_id}/credentials/{credential_id}/rotate:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - $ref: "#/components/parameters/EnvironmentId"
+      - $ref: "#/components/parameters/ApiCredentialId"
+    post:
+      operationId: rotateApiCredential
+      summary: Rotate an environment-scoped API credential
+      description: |
+        Creates one replacement with the same label and scopes. The complete new
+        bearer secret appears only in this response. The replaced credential
+        remains active for the explicitly declared overlap, from zero through
+        86400 seconds, then becomes terminally revoked. A revoked credential
+        cannot be rotated. Missing and out-of-scope credentials use the same
+        non-enumerating `404`.
+      tags:
+        - API credentials
+      security:
+        - clerkSession: []
+      x-account-membership: required
+      x-secret-reveal:
+        responses: 1
+        replayable: false
+        later_reads: metadata_only
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RotateApiCredentialRequest"
+            examples:
+              rotateCredential:
+                externalValue: ../fixtures/core-v1/requests/rotate-api-credential.json
+      responses:
+        "201":
+          description: Creation-only replacement secret and safe metadata for both credentials.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiCredentialRotation"
+              examples:
+                rotatedCredential:
+                  externalValue: ../fixtures/core-v1/success/api-credential-rotated.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/projects/{project_id}/environments/{environment_id}/credentials/{credential_id}/revoke:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - $ref: "#/components/parameters/EnvironmentId"
+      - $ref: "#/components/parameters/ApiCredentialId"
+    post:
+      operationId: revokeApiCredential
+      summary: Revoke an environment-scoped API credential
+      description: |
+        Immediately and terminally revokes the selected credential. Repeating
+        the request for the same visible credential is safe and returns the
+        same revoked metadata without revealing secret or digest material.
+        Missing and out-of-scope credentials use the same non-enumerating `404`.
+      tags:
+        - API credentials
+      security:
+        - clerkSession: []
+      x-account-membership: required
+      x-repeat-semantics:
+        same_target: idempotent
+        secret_returned: false
+      responses:
+        "200":
+          description: Safe terminal credential metadata.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiCredential"
+              examples:
+                revokedCredential:
+                  externalValue: ../fixtures/core-v1/success/api-credential-revoked.json
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/subscription-links:
+    post:
+      operationId: createSubscriptionLink
+      summary: Create a subscription link
+      description: |
+        Creates one single-use authorization link inside the authenticated
+        project and environment. Equivalent replay returns the original `201`
+        response and logical resource without extending idempotency retention.
+      tags:
+        - Subscription links
+      security:
+        - bearerCredential: []
+      x-required-scopes:
+        - subscriptions:write
+      x-idempotency:
+        required: true
+        retention_seconds: 604800
+        scope:
+          - authenticated_environment
+          - operation_id
+          - key
+        equivalence: validated_request_after_documented_defaults
+        replay_retention_extends: false
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateSubscriptionLinkRequest"
+            examples:
+              defaultTelegram:
+                externalValue: ../fixtures/core-v1/requests/create-subscription-link.json
+      responses:
+        "201":
+          description: A new link, or the original link and original status on equivalent replay.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SubscriptionLink"
+              examples:
+                pending:
+                  externalValue: ../fixtures/core-v1/success/subscription-link-pending.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "409":
+          $ref: "#/components/responses/Conflict"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/subscription-links/{subscription_link_id}:
+    parameters:
+      - $ref: "#/components/parameters/SubscriptionLinkId"
+    get:
+      operationId: getSubscriptionLink
+      summary: Inspect a subscription link
+      description: |
+        Returns the current link state. An activated or revoked link exposes an
+        opaque binding summary, never a Telegram chat or user identifier.
+        Cross-project and cross-environment identifiers return `404`.
+      tags:
+        - Subscription links
+      security:
+        - bearerCredential: []
+      x-required-scopes:
+        - subscriptions:read
+      responses:
+        "200":
+          description: Current link state.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SubscriptionLink"
+              examples:
+                activated:
+                  externalValue: ../fixtures/core-v1/success/subscription-link-activated.json
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/subscription-links/{subscription_link_id}/cancel:
+    parameters:
+      - $ref: "#/components/parameters/SubscriptionLinkId"
+    post:
+      operationId: cancelSubscriptionLink
+      summary: Cancel a pending subscription link
+      description: |
+        Cancels a pending link. Equivalent replay returns the original result.
+        Consumption of a cancelled or expired link never creates a binding.
+      tags:
+        - Subscription links
+      security:
+        - bearerCredential: []
+      x-required-scopes:
+        - subscriptions:write
+      x-idempotency:
+        required: true
+        retention_seconds: 604800
+        scope:
+          - authenticated_environment
+          - operation_id
+          - key
+        equivalence: validated_request_after_documented_defaults
+        replay_retention_extends: false
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
+      responses:
+        "200":
+          description: Current link state and whether cancellation took effect.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/SubscriptionLink"
+                  - type: object
+                    required:
+                      - cancellation_effective
+              examples:
+                cancelled:
+                  externalValue: ../fixtures/core-v1/success/subscription-link-cancelled.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/messages:
+    post:
+      operationId: createMessage
+      summary: Create an asynchronous message
+      description: |
+        Durably accepts one logical text message for one subscriber and one
+        resolved channel binding. `202` proves API acceptance only; it does not
+        claim provider acceptance or end-device delivery.
+      tags:
+        - Messages
+      security:
+        - bearerCredential: []
+        - machineCredential: []
+      x-required-scopes:
+        - messages:write
+      x-machine-required-scopes:
+        - machine-messages:write
+      x-machine-binding-enforcement:
+        - authenticated_project
+        - authenticated_environment
+        - bound_notifier
+        - bound_subscriber
+      x-idempotency:
+        required: true
+        retention_seconds: 604800
+        scope:
+          - authenticated_environment
+          - operation_id
+          - key
+        equivalence: validated_request_after_documented_defaults
+        replay_retention_extends: false
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateMessageRequest"
+            examples:
+              text:
+                externalValue: ../fixtures/core-v1/requests/create-message.json
+              confirm:
+                externalValue: ../fixtures/interaction-machine-v1/requests/create-message-confirm.json
+              select:
+                externalValue: ../fixtures/interaction-machine-v1/requests/create-message-select.json
+              input:
+                externalValue: ../fixtures/interaction-machine-v1/requests/create-message-input.json
+      responses:
+        "202":
+          description: A newly accepted message, or the original message and status on equivalent replay.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Message"
+              examples:
+                accepted:
+                  externalValue: ../fixtures/core-v1/success/message-accepted.json
+                interactionOpen:
+                  externalValue: ../fixtures/interaction-machine-v1/success/message-interaction-open.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "409":
+          $ref: "#/components/responses/Conflict"
+        "422":
+          $ref: "#/components/responses/Unprocessable"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/messages/{message_id}:
+    parameters:
+      - $ref: "#/components/parameters/MessageId"
+    get:
+      operationId: getMessage
+      summary: Inspect a message
+      description: |
+        Returns the canonical logical state and highest proven provider state.
+        `outcome_unknown` is distinct from retryable and terminal failure and
+        never has an automatic retry scheduled.
+
+        When the message has an open interaction, the optional bounded `wait`
+        holds this read for its canonical terminal state. A wait timeout is a
+        successful current-state read, not an error. Terminal interactions and
+        messages without an interaction return immediately. Inspection never
+        acknowledges, consumes, retries, replays, or changes delivery.
+      parameters:
+        - $ref: "#/components/parameters/ResponseInspectionWait"
+      tags:
+        - Messages
+      security:
+        - bearerCredential: []
+        - machineCredential: []
+      x-required-scopes:
+        - messages:read
+      x-machine-required-scopes:
+        - machine-messages:read
+      x-machine-binding-enforcement:
+        - authenticated_project
+        - authenticated_environment
+        - owning_machine_client
+      responses:
+        "200":
+          description: Current message and safe delivery-attempt summary.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Message"
+              examples:
+                providerAccepted:
+                  externalValue: ../fixtures/core-v1/success/message-provider-accepted.json
+                outcomeUnknown:
+                  externalValue: ../fixtures/core-v1/success/message-outcome-unknown.json
+                interactionOpen:
+                  externalValue: ../fixtures/interaction-machine-v1/success/message-interaction-open.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/interactions/{interaction_id}:
+    parameters:
+      - $ref: "#/components/parameters/InteractionId"
+    get:
+      operationId: getInteraction
+      summary: Inspect an interaction response
+      description: |
+        Returns the same canonical first-terminal-writer interaction summary
+        used by message status, signed customer events, and machine events.
+        An answered interaction always retains `answered` and `answered_at`;
+        `answer_retained` says whether the typed answer is still present.
+
+        The optional bounded `wait` holds an open interaction read for a
+        terminal state. Expiry without resolution returns the current `open`
+        summary successfully and can be immediately re-polled. Inspection is
+        read-only and has no effect on any delivery or retention lifecycle.
+      parameters:
+        - $ref: "#/components/parameters/ResponseInspectionWait"
+      tags:
+        - Messages
+      security:
+        - bearerCredential: []
+        - machineCredential: []
+      x-required-scopes:
+        - messages:read
+      x-machine-required-scopes:
+        - machine-messages:read
+      x-machine-binding-enforcement:
+        - authenticated_project
+        - authenticated_environment
+        - owning_machine_client
+      responses:
+        "200":
+          description: Current canonical interaction state and retained answer.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InteractionSummary"
+              examples:
+                open:
+                  externalValue: ../fixtures/interaction-machine-v1/success/interaction-open.json
+                answeredConfirm:
+                  externalValue: ../fixtures/interaction-machine-v1/success/interaction-answered-confirm.json
+                answeredSelect:
+                  externalValue: ../fixtures/interaction-machine-v1/success/interaction-answered-select.json
+                answeredInput:
+                  externalValue: ../fixtures/interaction-machine-v1/success/interaction-answered-input.json
+                answeredRedacted:
+                  externalValue: ../fixtures/interaction-machine-v1/success/interaction-answered-redacted.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/messages/{message_id}/cancel:
+    parameters:
+      - $ref: "#/components/parameters/MessageId"
+    post:
+      operationId: cancelMessage
+      summary: Cancel a message before provider-call ownership
+      description: |
+        Cancellation is effective only before a worker owns the provider call.
+        A race at `sending`, `provider_accepted`, or `outcome_unknown` returns
+        the current state with `cancellation_effective: false` and never claims
+        provider-side deletion.
+      tags:
+        - Messages
+      security:
+        - bearerCredential: []
+      x-required-scopes:
+        - messages:write
+      x-idempotency:
+        required: true
+        retention_seconds: 604800
+        scope:
+          - authenticated_environment
+          - operation_id
+          - key
+        equivalence: validated_request_after_documented_defaults
+        replay_retention_extends: false
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
+      responses:
+        "200":
+          description: Current message state and whether cancellation took effect.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/Message"
+                  - type: object
+                    required:
+                      - cancellation_effective
+              examples:
+                cancelled:
+                  externalValue: ../fixtures/core-v1/success/message-cancelled.json
+                tooLate:
+                  externalValue: ../fixtures/core-v1/success/message-cancellation-too-late.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/machine-clients:
+    post:
+      operationId: createMachineClient
+      summary: Create a destination-bound machine client
+      description: |
+        Creates one machine client in the project/environment selected by the
+        project credential. The notifier, subscriber, and active binding become
+        immutable authorization bounds. The response never contains a readable
+        secret or digest.
+      tags:
+        - Machine clients
+      security:
+        - bearerCredential: []
+      x-required-scopes:
+        - machine-clients:write
+      x-idempotency:
+        required: true
+        retention_seconds: 604800
+        scope:
+          - authenticated_environment
+          - operation_id
+          - key
+        equivalence: validated_request_after_documented_defaults
+        replay_retention_extends: false
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateMachineClientRequest"
+            examples:
+              localClient:
+                externalValue: ../fixtures/interaction-machine-v1/requests/create-machine-client.json
+      responses:
+        "201":
+          description: A new provisioning client or the original client on equivalent replay.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MachineClient"
+              examples:
+                provisioning:
+                  externalValue: ../fixtures/interaction-machine-v1/success/machine-client-provisioning.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "409":
+          $ref: "#/components/responses/Conflict"
+        "422":
+          $ref: "#/components/responses/Unprocessable"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/machine-clients/{machine_client_id}:
+    parameters:
+      - $ref: "#/components/parameters/MachineClientId"
+    get:
+      operationId: getMachineClient
+      summary: Inspect machine-client metadata
+      description: |
+        Returns only safe metadata inside the authenticated project/environment.
+        A client outside that scope is indistinguishable from an absent client.
+      tags:
+        - Machine clients
+      security:
+        - bearerCredential: []
+      x-required-scopes:
+        - machine-clients:read
+      responses:
+        "200":
+          description: Current machine-client metadata and fixed scope summary.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MachineClient"
+              examples:
+                active:
+                  externalValue: ../fixtures/interaction-machine-v1/success/machine-client-active.json
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/machine-clients/{machine_client_id}/credentials:
+    parameters:
+      - $ref: "#/components/parameters/MachineClientId"
+    post:
+      operationId: registerMachineCredential
+      summary: Register a locally generated machine-credential digest
+      description: |
+        Registers only the credential ID and SHA-256 digest. The same ID and
+        digest returns existing safe metadata; the same ID with another digest
+        conflicts. The first active credential activates a provisioning client.
+      tags:
+        - Machine clients
+      security:
+        - bearerCredential: []
+      x-required-scopes:
+        - machine-clients:write
+      x-idempotency:
+        required: true
+        retention_seconds: 604800
+        scope:
+          - authenticated_environment
+          - operation_id
+          - key
+        equivalence: validated_request_after_documented_defaults
+        replay_retention_extends: false
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RegisterMachineCredentialRequest"
+            examples:
+              digestOnly:
+                externalValue: ../fixtures/interaction-machine-v1/requests/register-machine-credential.json
+      responses:
+        "200":
+          description: Existing safe credential metadata on an equivalent registration replay; never secret or digest.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MachineCredential"
+              examples:
+                existing:
+                  externalValue: ../fixtures/interaction-machine-v1/success/machine-credential-active.json
+        "201":
+          description: Newly registered safe credential metadata; never secret or digest.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MachineCredential"
+              examples:
+                active:
+                  externalValue: ../fixtures/interaction-machine-v1/success/machine-credential-active.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/machine-clients/{machine_client_id}/credentials/{credential_id}/revoke:
+    parameters:
+      - $ref: "#/components/parameters/MachineClientId"
+      - $ref: "#/components/parameters/MachineCredentialId"
+    post:
+      operationId: revokeMachineCredential
+      summary: Revoke a machine credential
+      description: |
+        Idempotently ends new authorization by this credential. Rotation
+        registers and smoke-tests a replacement before this operation.
+      tags:
+        - Machine clients
+      security:
+        - bearerCredential: []
+      x-required-scopes:
+        - machine-clients:write
+      x-idempotency:
+        required: true
+        retention_seconds: 604800
+        scope:
+          - authenticated_environment
+          - operation_id
+          - key
+        equivalence: validated_request_after_documented_defaults
+        replay_retention_extends: false
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
+      responses:
+        "200":
+          description: Safe revoked credential metadata.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MachineCredential"
+              examples:
+                revoked:
+                  externalValue: ../fixtures/interaction-machine-v1/success/machine-credential-revoked.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/machine-clients/{machine_client_id}/revoke:
+    parameters:
+      - $ref: "#/components/parameters/MachineClientId"
+    post:
+      operationId: revokeMachineClient
+      summary: Revoke a machine client
+      description: |
+        Idempotently revokes the client and all new credential authorization.
+        Existing messages and immutable events are retained under contract.
+      tags:
+        - Machine clients
+      security:
+        - bearerCredential: []
+      x-required-scopes:
+        - machine-clients:write
+      x-idempotency:
+        required: true
+        retention_seconds: 604800
+        scope:
+          - authenticated_environment
+          - operation_id
+          - key
+        equivalence: validated_request_after_documented_defaults
+        replay_retention_extends: false
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
+      responses:
+        "200":
+          description: Safe revoked client metadata.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MachineClient"
+              examples:
+                revoked:
+                  externalValue: ../fixtures/interaction-machine-v1/success/machine-client-revoked.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/machine-events:
+    get:
+      operationId: pollMachineEvents
+      summary: Long-poll the authenticated machine stream
+      description: |
+        Polls only the stream selected by the machine credential. `after` is
+        omitted only on the first poll and otherwise must equal the exact
+        atomically committed cursor returned for this stream. Any other cursor,
+        including a known issued but uncommitted cursor, fails closed and never
+        rewinds. Unacknowledged events may repeat with the same event ID and
+        cursor.
+      tags:
+        - Machine events
+      security:
+        - machineCredential: []
+      x-required-scopes:
+        - machine-events:read
+      x-event-retention:
+        minimum_seconds_after_creation: 604800
+        extends_interaction_answer_authority: false
+      parameters:
+        - $ref: "#/components/parameters/MachineAfterCursor"
+        - $ref: "#/components/parameters/MachinePollWait"
+        - $ref: "#/components/parameters/MachinePollLimit"
+      responses:
+        "200":
+          description: Stable ordered events and the atomically committed cursor.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MachineEventPollResponse"
+              examples:
+                events:
+                  externalValue: ../fixtures/interaction-machine-v1/success/poll-events.json
+                empty:
+                  externalValue: ../fixtures/interaction-machine-v1/success/poll-empty.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/machine-events/{event_id}/ack:
+    parameters:
+      - $ref: "#/components/parameters/MachineEventId"
+    post:
+      operationId: ackMachineEvent
+      summary: Record a per-event machine acknowledgement
+      description: |
+        Records processed or permitted quarantine disposition idempotently.
+        The committed cursor advances only across a contiguous acknowledged
+        prefix. Authentication, stream identity, signature, and schema failures
+        cannot be quarantined to skip work.
+      tags:
+        - Machine events
+      security:
+        - machineCredential: []
+      x-required-scopes:
+        - machine-events:ack
+      x-idempotency:
+        required: true
+        retention_seconds: 604800
+        scope:
+          - authenticated_environment
+          - operation_id
+          - key
+        equivalence: validated_request_after_documented_defaults
+        replay_retention_extends: false
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/MachineEventAckRequest"
+            examples:
+              processed:
+                externalValue: ../fixtures/interaction-machine-v1/requests/ack-processed.json
+              quarantined:
+                externalValue: ../fixtures/interaction-machine-v1/requests/ack-quarantined.json
+      responses:
+        "200":
+          description: New or existing acknowledgement and current committed position.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MachineEventAckResponse"
+              examples:
+                processed:
+                  externalValue: ../fixtures/interaction-machine-v1/success/ack-processed.json
+                outOfOrder:
+                  externalValue: ../fixtures/interaction-machine-v1/success/ack-out-of-order.json
+                quarantined:
+                  externalValue: ../fixtures/interaction-machine-v1/success/ack-quarantined.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/projects/{project_id}/environments/{environment_id}/customer-endpoints:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - $ref: "#/components/parameters/EnvironmentId"
+    get:
+      operationId: listCustomerEndpoints
+      summary: List safe customer-endpoint health metadata
+      tags:
+        - Customer endpoints
+      security:
+        - clerkSession: []
+        - bearerCredential: []
+        - bearerGrant: []
+      x-required-scopes:
+        - messages:read
+      responses:
+        "200":
+          description: Safe endpoint lifecycle and health metadata without URLs or protected content.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CustomerEndpointCollection"
+              examples:
+                endpoints:
+                  externalValue: ../fixtures/core-v1/success/customer-endpoint-collection.json
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+    post:
+      operationId: createCustomerEndpoint
+      summary: Create an inactive customer endpoint and reveal its signing secret once
+      description: |
+        Validates the final normalized public HTTPS destination before storing it.
+        The initial response includes the new signing secret. An equivalent
+        idempotent replay returns the same logical endpoint without the secret;
+        different input for the same key returns `idempotency_conflict`.
+      tags:
+        - Customer endpoints
+      security:
+        - clerkSession: []
+        - bearerCredential: []
+        - bearerGrant: []
+      x-required-scopes:
+        - messages:write
+      x-idempotency:
+        required: true
+        retention_seconds: 604800
+        scope:
+          - authenticated_environment
+          - operation_id
+          - key
+        equivalence: final_normalized_url_and_validated_request
+        replay_retention_extends: false
+      x-secret-reveal:
+        responses: 1
+        replayable: false
+        later_reads: metadata_only
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateCustomerEndpointRequest"
+            examples:
+              createEndpoint:
+                externalValue: ../fixtures/core-v1/requests/create-customer-endpoint.json
+      responses:
+        "201":
+          description: Newly created unverified endpoint and its one-time signing secret.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CustomerEndpointMutationResult"
+              examples:
+                created:
+                  externalValue: ../fixtures/core-v1/success/customer-endpoint-created.json
+        "200":
+          description: Equivalent replay returning safe endpoint metadata without the secret.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CustomerEndpointMutationResult"
+              examples:
+                replayed:
+                  externalValue: ../fixtures/core-v1/success/customer-endpoint-create-replayed.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+        "503":
+          $ref: "#/components/responses/ProviderRetryable"
+  /v1/projects/{project_id}/environments/{environment_id}/customer-endpoints/{endpoint_id}:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - $ref: "#/components/parameters/EnvironmentId"
+      - $ref: "#/components/parameters/CustomerEndpointId"
+    get:
+      operationId: getCustomerEndpoint
+      summary: Read safe lifecycle and health metadata for one endpoint
+      tags:
+        - Customer endpoints
+      security:
+        - clerkSession: []
+        - bearerCredential: []
+        - bearerGrant: []
+      x-required-scopes:
+        - messages:read
+      responses:
+        "200":
+          description: Safe endpoint metadata.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CustomerEndpoint"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /v1/projects/{project_id}/environments/{environment_id}/customer-endpoints/{endpoint_id}/verify:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - $ref: "#/components/parameters/EnvironmentId"
+      - $ref: "#/components/parameters/CustomerEndpointId"
+    post:
+      operationId: verifyCustomerEndpoint
+      summary: Send a signed challenge and activate the endpoint only after a signed echo
+      tags:
+        - Customer endpoints
+      security:
+        - clerkSession: []
+        - bearerCredential: []
+        - bearerGrant: []
+      x-required-scopes:
+        - messages:write
+      responses:
+        "200":
+          description: Verified active endpoint metadata.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CustomerEndpoint"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "502":
+          $ref: "#/components/responses/ProviderTerminal"
+        "503":
+          $ref: "#/components/responses/ProviderRetryable"
+  /v1/projects/{project_id}/environments/{environment_id}/customer-endpoints/{endpoint_id}/rotate:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - $ref: "#/components/parameters/EnvironmentId"
+      - $ref: "#/components/parameters/CustomerEndpointId"
+    post:
+      operationId: rotateCustomerEndpoint
+      summary: Create a new signing version with bounded old/new overlap
+      tags:
+        - Customer endpoints
+      security:
+        - clerkSession: []
+        - bearerCredential: []
+        - bearerGrant: []
+      x-required-scopes:
+        - messages:write
+      x-idempotency:
+        required: true
+        retention_seconds: 604800
+        scope:
+          - authenticated_environment
+          - operation_id
+          - key
+        equivalence: endpoint_and_validated_request
+        replay_retention_extends: false
+      x-secret-reveal:
+        responses: 1
+        replayable: false
+        later_reads: metadata_only
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RotateCustomerEndpointRequest"
+            examples:
+              rotate:
+                externalValue: ../fixtures/core-v1/requests/rotate-customer-endpoint.json
+      responses:
+        "201":
+          description: Rotated endpoint and one-time new secret.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CustomerEndpointMutationResult"
+              examples:
+                rotated:
+                  externalValue: ../fixtures/core-v1/success/customer-endpoint-rotated.json
+        "200":
+          description: Equivalent replay without another secret reveal.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CustomerEndpointMutationResult"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/EndpointRotationConflict"
+  /v1/projects/{project_id}/environments/{environment_id}/customer-endpoints/{endpoint_id}/{action}:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - $ref: "#/components/parameters/EnvironmentId"
+      - $ref: "#/components/parameters/CustomerEndpointId"
+      - name: action
+        in: path
+        required: true
+        schema:
+          type: string
+          enum: [pause, resume, disable]
+    post:
+      operationId: transitionCustomerEndpoint
+      summary: Pause, resume, or terminally disable an endpoint
+      tags:
+        - Customer endpoints
+      security:
+        - clerkSession: []
+        - bearerCredential: []
+        - bearerGrant: []
+      x-required-scopes:
+        - messages:write
+      x-repeat-semantics:
+        same_target: idempotent
+        secret_returned: false
+      responses:
+        "200":
+          description: Updated safe endpoint metadata.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CustomerEndpoint"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /v1/projects/{project_id}/environments/{environment_id}/customer-endpoints/{endpoint_id}/attempts:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - $ref: "#/components/parameters/EnvironmentId"
+      - $ref: "#/components/parameters/CustomerEndpointId"
+    get:
+      operationId: listCustomerEndpointAttempts
+      summary: Inspect protected content-free delivery diagnostics
+      tags:
+        - Customer endpoints
+      security:
+        - clerkSession: []
+        - bearerCredential: []
+        - bearerGrant: []
+      x-required-scopes:
+        - messages:read
+      responses:
+        "200":
+          description: Safe status, timing, and failure categories only.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CustomerEndpointAttemptCollection"
+              examples:
+                attempts:
+                  externalValue: ../fixtures/core-v1/success/customer-endpoint-attempts.json
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /v1/capabilities:
+    get:
+      operationId: getCapabilities
+      summary: Inspect provider-neutral capabilities
+      tags:
+        - Capabilities
+      security:
+        - bearerCredential: []
+      x-required-scopes:
+        - capabilities:read
+      responses:
+        "200":
+          description: Current stable capability vocabulary and active degradation.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProviderCapabilitiesCollection"
+              examples:
+                providers:
+                  externalValue: ../fixtures/interaction-machine-v1/capabilities/providers.json
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/projects/{project_id}/environments/{environment_id}/subscription-links:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - $ref: "#/components/parameters/EnvironmentId"
+    post:
+      operationId: createSubscriptionLinkInEnvironment
+      summary: Create a subscription link in a named project environment
+      description: |
+        The environment-scoped form of `createSubscriptionLink`, for a caller
+        whose authority selects an account rather than a project. Behavior,
+        request, and response are identical; the path names the scope the
+        credential form takes from its bearer, and the service checks it
+        against the granting person's membership before acting.
+      tags:
+        - Subscription links
+      security:
+        - bearerGrant: []
+      x-required-scopes:
+        - subscriptions:write
+      x-idempotency:
+        required: true
+        retention_seconds: 604800
+        scope:
+          - authenticated_account
+          - operation_id
+          - key
+        equivalence: validated_request
+        replay_retention_extends: false
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateSubscriptionLinkRequest"
+      responses:
+        "201":
+          description: The link was created in the named environment.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SubscriptionLink"
+              examples:
+                pending:
+                  externalValue: ../fixtures/core-v1/success/subscription-link-pending.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/projects/{project_id}/environments/{environment_id}/subscription-links/{subscription_link_id}:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - $ref: "#/components/parameters/EnvironmentId"
+      - $ref: "#/components/parameters/SubscriptionLinkId"
+    get:
+      operationId: getSubscriptionLinkInEnvironment
+      summary: Inspect a subscription link in a named project environment
+      description: |
+        The environment-scoped form of `getSubscriptionLink`. A link outside the
+        named environment is absent, exactly as it is for a credential.
+      tags:
+        - Subscription links
+      security:
+        - bearerGrant: []
+      x-required-scopes:
+        - subscriptions:read
+      responses:
+        "200":
+          description: Current link state and, once completed, its safe binding summary.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SubscriptionLink"
+              examples:
+                activated:
+                  externalValue: ../fixtures/core-v1/success/subscription-link-activated.json
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/projects/{project_id}/environments/{environment_id}/messages:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - $ref: "#/components/parameters/EnvironmentId"
+    post:
+      operationId: createMessageInEnvironment
+      summary: Create an asynchronous message in a named project environment
+      description: |
+        The environment-scoped form of `createMessage`. The path names the
+        account, project, and environment the credential form takes from its
+        bearer; test and live remain a property of the named environment and are
+        never selected by the request body.
+      tags:
+        - Messages
+      security:
+        - bearerGrant: []
+      x-required-scopes:
+        - messages:write
+      x-idempotency:
+        required: true
+        retention_seconds: 604800
+        scope:
+          - authenticated_account
+          - operation_id
+          - key
+        equivalence: validated_request
+        replay_retention_extends: false
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateMessageRequest"
+      responses:
+        "202":
+          description: The message was accepted in the named environment.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Message"
+              examples:
+                accepted:
+                  externalValue: ../fixtures/core-v1/success/message-accepted.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+        "422":
+          $ref: "#/components/responses/Unprocessable"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/projects/{project_id}/environments/{environment_id}/messages/{message_id}:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - $ref: "#/components/parameters/EnvironmentId"
+      - $ref: "#/components/parameters/MessageId"
+    get:
+      operationId: getMessageInEnvironment
+      summary: Inspect a message in a named project environment
+      description: |
+        The environment-scoped form of `getMessage`, including the same bounded
+        long poll. Inspection acknowledges, consumes, retries, and replays
+        nothing.
+      parameters:
+        - $ref: "#/components/parameters/ResponseInspectionWait"
+      tags:
+        - Messages
+      security:
+        - bearerGrant: []
+      x-required-scopes:
+        - messages:read
+      responses:
+        "200":
+          description: Canonical message state at the moment the read completed.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Message"
+              examples:
+                accepted:
+                  externalValue: ../fixtures/core-v1/success/message-provider-accepted.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/projects/{project_id}/environments/{environment_id}/interactions/{interaction_id}:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - $ref: "#/components/parameters/EnvironmentId"
+      - $ref: "#/components/parameters/InteractionId"
+    get:
+      operationId: getInteractionInEnvironment
+      summary: Inspect an interaction response in a named project environment
+      description: |
+        The environment-scoped form of `getInteraction`, including the same
+        bounded long poll and the same retained-answer semantics.
+      parameters:
+        - $ref: "#/components/parameters/ResponseInspectionWait"
+      tags:
+        - Messages
+      security:
+        - bearerGrant: []
+      x-required-scopes:
+        - messages:read
+      responses:
+        "200":
+          description: Canonical interaction state at the moment the read completed.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InteractionSummary"
+              examples:
+                answered:
+                  externalValue: ../fixtures/interaction-machine-v1/success/interaction-answered-confirm.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/projects/{project_id}/environments/{environment_id}/machine-clients:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - $ref: "#/components/parameters/EnvironmentId"
+    post:
+      operationId: createMachineClientInEnvironment
+      summary: Create a destination-bound machine client in a named project environment
+      description: |
+        The environment-scoped form of `createMachineClient`. Scope remains the
+        exact bound destination; the path only names where the client is created.
+      tags:
+        - Machine clients
+      security:
+        - bearerGrant: []
+      x-required-scopes:
+        - machine-clients:write
+      x-idempotency:
+        required: true
+        retention_seconds: 604800
+        scope:
+          - authenticated_account
+          - operation_id
+          - key
+        equivalence: validated_request
+        replay_retention_extends: false
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateMachineClientRequest"
+      responses:
+        "201":
+          description: The machine client was created in the named environment.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MachineClient"
+              examples:
+                provisioning:
+                  externalValue: ../fixtures/interaction-machine-v1/success/machine-client-provisioning.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+        "422":
+          $ref: "#/components/responses/Unprocessable"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/projects/{project_id}/environments/{environment_id}/capabilities:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - $ref: "#/components/parameters/EnvironmentId"
+    get:
+      operationId: getCapabilitiesInEnvironment
+      summary: Inspect provider-neutral capabilities for a named project environment
+      description: |
+        The environment-scoped form of `getCapabilities`. The vocabulary is
+        provider-neutral and identical; the path names the environment whose
+        active degradation is reported.
+      tags:
+        - Capabilities
+      security:
+        - bearerGrant: []
+      x-required-scopes:
+        - capabilities:read
+      responses:
+        "200":
+          description: Current stable capability vocabulary and active degradation.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProviderCapabilitiesCollection"
+              examples:
+                providers:
+                  externalValue: ../fixtures/interaction-machine-v1/capabilities/providers.json
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+components:
+  securitySchemes:
+    clerkSession:
+      type: http
+      scheme: bearer
+      bearerFormat: Clerk session JWT
+      description: |
+        A verified human session whose active Clerk organization selects exactly
+        one WhooshBang account. Every administration operation rechecks the
+        projected account membership; session identity never selects a project
+        or environment from request data.
+    bearerGrant:
+      type: http
+      scheme: bearer
+      bearerFormat: OAuth 2.0 access token
+      description: |
+        An access token issued by the WhooshBang authorization server for one
+        consenting account member. It selects exactly one account and carries
+        the scopes that member consented to, and never a project: an operation
+        names its project and environment in the path, and the service checks
+        both against the granting person's membership before acting. It can
+        hold account-level scopes, which no credential can.
+    bearerCredential:
+      type: http
+      scheme: bearer
+      bearerFormat: wb_pc1.pcred_<16-byte-base64url>.<32-byte-base64url-secret>
+      description: |
+        Selects exactly one account, project, and `test` or `live` environment.
+        Credentials cannot be read after creation. Except for explicitly
+        synthetic creation/rotation reveal fixtures, complete bearer values
+        must never appear in fixtures, errors, logs, metrics, or inspection
+        surfaces.
+    machineCredential:
+      type: http
+      scheme: bearer
+      bearerFormat: wb_mc1.mcred_<16-byte-base64url>.<32-byte-base64url-secret>
+      description: |
+        A locally generated runtime credential bound server-side to exactly one
+        project/environment, machine client, notifier, subscriber, binding, and
+        event stream. Project credentials cannot use machine-only endpoints.
+        Revoked credentials fail before resource lookup.
+  parameters:
+    IdempotencyKey:
+      name: Idempotency-Key
+      in: header
+      required: true
+      description: |
+        Visible ASCII key retained for seven days from first acceptance.
+        Equivalent replay returns the original status and logical resource;
+        materially different validated input returns `idempotency_conflict`.
+      schema:
+        $ref: "#/components/schemas/IdempotencyKey"
+    SubscriptionLinkId:
+      name: subscription_link_id
+      in: path
+      required: true
+      description: Opaque subscription-link identity; never authorization.
+      schema:
+        $ref: "#/components/schemas/OpaqueIdentifier"
+    ProjectId:
+      name: project_id
+      in: path
+      required: true
+      description: Opaque project identity; never authorization.
+      schema:
+        $ref: "#/components/schemas/OpaqueIdentifier"
+    EnvironmentId:
+      name: environment_id
+      in: path
+      required: true
+      description: Opaque project-environment identity; never authorization.
+      schema:
+        $ref: "#/components/schemas/OpaqueIdentifier"
+    ApiCredentialId:
+      name: credential_id
+      in: path
+      required: true
+      description: Canonical opaque project credential identity; never a readable secret.
+      schema:
+        $ref: "#/components/schemas/ApiCredentialId"
+    ApiCredentialAfterCursor:
+      name: after
+      in: query
+      required: false
+      description: Opaque cursor returned by the previous credential page.
+      schema:
+        type: string
+        minLength: 1
+        maxLength: 256
+        pattern: "^[A-Za-z0-9_-]+$"
+    ApiCredentialPageLimit:
+      name: limit
+      in: query
+      required: false
+      description: Maximum credential metadata records returned in one page.
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 100
+        default: 50
+    ProjectAfterCursor:
+      name: after
+      in: query
+      required: false
+      description: Opaque cursor returned by the previous project page.
+      schema:
+        type: string
+        minLength: 1
+        maxLength: 256
+        pattern: "^[A-Za-z0-9_-]+$"
+    ProjectPageLimit:
+      name: limit
+      in: query
+      required: false
+      description: Maximum projects returned in one page.
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 100
+        default: 50
+    MessageId:
+      name: message_id
+      in: path
+      required: true
+      description: Opaque logical message identity; never authorization.
+      schema:
+        $ref: "#/components/schemas/OpaqueIdentifier"
+    InteractionId:
+      name: interaction_id
+      in: path
+      required: true
+      description: Opaque interaction identity; never authorization.
+      schema:
+        $ref: "#/components/schemas/OpaqueIdentifier"
+    MachineClientId:
+      name: machine_client_id
+      in: path
+      required: true
+      description: Opaque machine-client identity; never authorization.
+      schema:
+        $ref: "#/components/schemas/OpaqueIdentifier"
+    MachineCredentialId:
+      name: credential_id
+      in: path
+      required: true
+      description: Canonical opaque credential identifier; never a readable secret.
+      schema:
+        $ref: "#/components/schemas/MachineCredentialId"
+    MachineEventId:
+      name: event_id
+      in: path
+      required: true
+      description: Opaque event identity constrained to the authenticated machine stream.
+      schema:
+        $ref: "#/components/schemas/OpaqueIdentifier"
+    CustomerEndpointId:
+      name: endpoint_id
+      in: path
+      required: true
+      description: Opaque endpoint identity; never authorization and never a URL.
+      schema:
+        $ref: "#/components/schemas/OpaqueIdentifier"
+    MachineAfterCursor:
+      name: after
+      in: query
+      required: false
+      description: |
+        Exact atomically committed cursor returned by the previous successful
+        poll or acknowledgement. Omit only for the first poll. A foreign,
+        unknown, or known-but-uncommitted cursor fails closed and cannot rewind
+        the stream.
+      schema:
+        $ref: "#/components/schemas/MachineCursor"
+    MachinePollWait:
+      name: wait
+      in: query
+      required: false
+      description: Bounded server hold time in seconds.
+      schema:
+        type: integer
+        minimum: 0
+        maximum: 30
+        default: 30
+    ResponseInspectionWait:
+      name: wait
+      in: query
+      required: false
+      description: |
+        Bounded server hold time in whole seconds. Omission defaults to 30;
+        zero requests an immediate read. A wait that expires returns the
+        current resource successfully rather than a timeout problem.
+      schema:
+        type: integer
+        minimum: 0
+        maximum: 30
+        default: 30
+    MachinePollLimit:
+      name: limit
+      in: query
+      required: false
+      description: Maximum stable-ordered events returned.
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 50
+        default: 25
+  headers:
+    DiagnosticId:
+      description: Safe public correlation identifier for protected diagnostics.
+      schema:
+        $ref: "#/components/schemas/DiagnosticId"
+  schemas:
+    OpaqueIdentifier:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/OpaqueIdentifier
+    DiagnosticId:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/DiagnosticId
+    IdempotencyKey:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/IdempotencyKey
+    AccountProjection:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/AccountProjection
+    CreateProjectRequest:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/CreateProjectRequest
+    DefaultNotifierSummary:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/DefaultNotifierSummary
+    ProjectEnvironment:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/ProjectEnvironment
+    Project:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/Project
+    ProjectCollection:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/ProjectCollection
+    CreateApiCredentialRequest:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/CreateApiCredentialRequest
+    RotateApiCredentialRequest:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/RotateApiCredentialRequest
+    ApiCredentialId:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/ApiCredentialId
+    ApiCredential:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/ApiCredential
+    ApiCredentialCollection:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/ApiCredentialCollection
+    ApiCredentialSecretReveal:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/ApiCredentialSecretReveal
+    ApiCredentialRotation:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/ApiCredentialRotation
+    CreateCustomerEndpointRequest:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/CreateCustomerEndpointRequest
+    RotateCustomerEndpointRequest:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/RotateCustomerEndpointRequest
+    CustomerEndpoint:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/CustomerEndpoint
+    CustomerEndpointCollection:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/CustomerEndpointCollection
+    CustomerEndpointMutationResult:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/CustomerEndpointMutationResult
+    CustomerEndpointAttemptCollection:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/CustomerEndpointAttemptCollection
+    CustomerEndpointVerificationChallenge:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/CustomerEndpointVerificationChallenge
+    BindingSummary:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/BindingSummary
+    CreateSubscriptionLinkRequest:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/CreateSubscriptionLinkRequest
+    SubscriptionLink:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/SubscriptionLink
+    CreateMessageRequest:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/CreateMessageRequest
+    DeliveryAttemptSummary:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/DeliveryAttemptSummary
+    Message:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/Message
+    Problem:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/Problem
+    InteractionRequest:
+      $ref: ../schemas/interaction-v1.schema.json#/$defs/InteractionRequest
+    InteractionSummary:
+      $ref: ../schemas/interaction-v1.schema.json#/$defs/InteractionSummary
+    InteractionEvent:
+      $ref: ../schemas/interaction-v1.schema.json#/$defs/InteractionEvent
+    CreateMachineClientRequest:
+      $ref: ../schemas/machine-v1.schema.json#/$defs/CreateMachineClientRequest
+    MachineClient:
+      $ref: ../schemas/machine-v1.schema.json#/$defs/MachineClient
+    MachineCredentialId:
+      $ref: ../schemas/machine-v1.schema.json#/$defs/MachineCredentialId
+    RegisterMachineCredentialRequest:
+      $ref: ../schemas/machine-v1.schema.json#/$defs/RegisterMachineCredentialRequest
+    MachineCredential:
+      $ref: ../schemas/machine-v1.schema.json#/$defs/MachineCredential
+    MachineCursor:
+      $ref: ../schemas/machine-v1.schema.json#/$defs/MachineCursor
+    MachineEventPollResponse:
+      $ref: ../schemas/machine-v1.schema.json#/$defs/MachineEventPollResponse
+    MachineEventAckRequest:
+      $ref: ../schemas/machine-v1.schema.json#/$defs/MachineEventAckRequest
+    MachineEventAckResponse:
+      $ref: ../schemas/machine-v1.schema.json#/$defs/MachineEventAckResponse
+    ProviderCapabilities:
+      $ref: ../schemas/provider-capabilities-v1.schema.json
+    ProviderCapabilitiesCollection:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/ProviderCapabilitiesCollection
+  responses:
+    BadRequest:
+      description: The request or required idempotency key is invalid.
+      headers:
+        WhooshBang-Diagnostic-Id:
+          $ref: "#/components/headers/DiagnosticId"
+      content:
+        application/problem+json:
+          schema:
+            $ref: "#/components/schemas/Problem"
+          examples:
+            requestInvalid:
+              externalValue: ../fixtures/core-v1/problems/request-invalid.json
+            idempotencyKeyRequired:
+              externalValue: ../fixtures/core-v1/problems/idempotency-key-required.json
+    Unauthorized:
+      description: A bearer credential is absent, malformed, invalid, or revoked.
+      headers:
+        WhooshBang-Diagnostic-Id:
+          $ref: "#/components/headers/DiagnosticId"
+      content:
+        application/problem+json:
+          schema:
+            $ref: "#/components/schemas/Problem"
+          examples:
+            authenticationRequired:
+              externalValue: ../fixtures/core-v1/problems/authentication-required.json
+            credentialInvalid:
+              externalValue: ../fixtures/core-v1/problems/auth-invalid.json
+    Forbidden:
+      description: The credential lacks scope or cannot address the requested environment.
+      headers:
+        WhooshBang-Diagnostic-Id:
+          $ref: "#/components/headers/DiagnosticId"
+      content:
+        application/problem+json:
+          schema:
+            $ref: "#/components/schemas/Problem"
+          examples:
+            scopeForbidden:
+              externalValue: ../fixtures/core-v1/problems/scope-forbidden.json
+            environmentMismatch:
+              externalValue: ../fixtures/core-v1/problems/environment-mismatch.json
+    NotFound:
+      description: |
+        The resource is absent or outside the authenticated project/environment.
+        The response never confirms cross-tenant existence.
+      headers:
+        WhooshBang-Diagnostic-Id:
+          $ref: "#/components/headers/DiagnosticId"
+      content:
+        application/problem+json:
+          schema:
+            $ref: "#/components/schemas/Problem"
+          examples:
+            resourceNotFound:
+              externalValue: ../fixtures/core-v1/problems/resource-not-found.json
+            resourceExpired:
+              externalValue: ../fixtures/core-v1/problems/resource-expired.json
+    Conflict:
+      description: |
+        An idempotency key, project slug, credential identity, existing
+        acknowledgement, or resource state conflicts with the authorized
+        account or request.
+      headers:
+        WhooshBang-Diagnostic-Id:
+          $ref: "#/components/headers/DiagnosticId"
+      content:
+        application/problem+json:
+          schema:
+            $ref: "#/components/schemas/Problem"
+          examples:
+            idempotencyConflict:
+              externalValue: ../fixtures/core-v1/problems/idempotency-conflict.json
+            projectSlugConflict:
+              externalValue: ../fixtures/core-v1/problems/project-slug-conflict.json
+            replayUnavailable:
+              externalValue: ../fixtures/core-v1/problems/replay-unavailable-rollout.json
+    Unprocessable:
+      description: The destination is valid in shape but has no authorized channel binding.
+      headers:
+        WhooshBang-Diagnostic-Id:
+          $ref: "#/components/headers/DiagnosticId"
+      content:
+        application/problem+json:
+          schema:
+            $ref: "#/components/schemas/Problem"
+          examples:
+            subscriberUnbound:
+              externalValue: ../fixtures/core-v1/problems/subscriber-unbound.json
+    ProviderTerminal:
+      description: The endpoint challenge failed in a way that requires developer action.
+      headers:
+        WhooshBang-Diagnostic-Id:
+          $ref: "#/components/headers/DiagnosticId"
+      content:
+        application/problem+json:
+          schema:
+            $ref: "#/components/schemas/Problem"
+          examples:
+            providerTerminal:
+              externalValue: ../fixtures/core-v1/problems/provider-terminal.json
+    ProviderRetryable:
+      description: The endpoint challenge failed transiently and can be retried safely.
+      headers:
+        WhooshBang-Diagnostic-Id:
+          $ref: "#/components/headers/DiagnosticId"
+      content:
+        application/problem+json:
+          schema:
+            $ref: "#/components/schemas/Problem"
+          examples:
+            providerRetryable:
+              externalValue: ../fixtures/core-v1/problems/provider-retryable.json
+    EndpointRotationConflict:
+      description: A previous signing-secret overlap must finish before another rotation.
+      headers:
+        WhooshBang-Diagnostic-Id:
+          $ref: "#/components/headers/DiagnosticId"
+      content:
+        application/problem+json:
+          schema:
+            $ref: "#/components/schemas/Problem"
+          examples:
+            endpointRotationConflict:
+              externalValue: ../fixtures/core-v1/problems/endpoint-rotation-conflict.json
+    RateLimited:
+      description: A project or operation rate limit was exceeded.
+      headers:
+        WhooshBang-Diagnostic-Id:
+          $ref: "#/components/headers/DiagnosticId"
+        Retry-After:
+          description: Safe delay in seconds when known.
+          schema:
+            type: integer
+            minimum: 1
+      content:
+        application/problem+json:
+          schema:
+            $ref: "#/components/schemas/Problem"
+          examples:
+            rateLimited:
+              externalValue: ../fixtures/core-v1/problems/rate-limited.json