@whooshbang/contracts 2.4.0 → 2.6.0

package/openapi/whooshbang-v1.yaml

@@ -1,10 +1,10 @@
 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: 2.4.0
+x-contract-version: 2.6.0
 info:
   title: WhooshBang API
-  version: 2.4.0
+  version: 2.6.0
   description: |
     The V1 contract for human organization/project administration, project-scoped
     subscription links, and asynchronous text messages. A Clerk session selects
@@ -435,6 +435,93 @@ paths:
           $ref: "#/components/responses/Conflict"
         "429":
           $ref: "#/components/responses/RateLimited"
+  /v1/billing/promotions:
+    get:
+      operationId: getBillingPromotions
+      summary: Read the organization's promotions
+      description: |
+        Organization administrators can read every promotion the organization holds: rewards WhooshBang gave it
+        and promotion codes it redeemed, with what remains and when each ends. Promotional value has no cash
+        value, is never refunded and cannot move to another organization.
+      tags: [Organization]
+      security:
+        - clerkSession: []
+        - bearerGrant: []
+      x-required-scopes: [billing:read]
+      x-organization-membership: required
+      responses:
+        "200":
+          description: The organization's promotions, newest first.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BillingPromotions"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/billing/promotions/redeem:
+    post:
+      operationId: redeemBillingPromotion
+      summary: Redeem a promotion code
+      description: |
+        Organization administrators can redeem a promotion code for their own organization. Nothing is charged.
+        Every code that cannot be redeemed (mistyped, ended, fully used, not offered to this organization, or not
+        combinable with a promotion it already holds) receives the same `resource_not_found` answer. Repeated
+        refusals are rate limited per organization; wait for `Retry-After`. Reuse the same idempotency key after
+        an uncertain response: it can never redeem twice.
+      tags: [Organization]
+      security:
+        - clerkSession: []
+        - bearerGrant: []
+      x-required-scopes: [billing:write]
+      x-organization-membership: required
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RedeemBillingPromotionRequest"
+      responses:
+        "200":
+          description: The same promotion, replayed for a repeated idempotency key.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BillingPromotion"
+        "201":
+          description: The promotion the code gave the organization.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BillingPromotion"
+        "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/billing/auto-top-up:
     get:
       operationId: getAutoTopUpSettings
@@ -2043,7 +2130,7 @@ paths:
         - projects:write
       x-organization-membership: required
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_organization
@@ -2529,7 +2616,7 @@ paths:
       x-required-scopes:
         - subscriptions:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_environment
@@ -2624,7 +2711,7 @@ paths:
       x-required-scopes:
         - subscriptions:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_environment
@@ -2685,7 +2772,7 @@ paths:
       x-required-scopes:
         - messages:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_environment
@@ -2812,7 +2899,7 @@ paths:
         - bound_notifier
         - bound_subscriber
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_environment
@@ -3002,7 +3089,7 @@ paths:
       x-required-scopes:
         - messages:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_environment
@@ -3061,7 +3148,7 @@ paths:
       x-required-scopes:
         - machine-clients:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_environment
@@ -3158,7 +3245,7 @@ paths:
       x-required-scopes:
         - machine-clients:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_environment
@@ -3231,7 +3318,7 @@ paths:
       x-required-scopes:
         - machine-clients:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_environment
@@ -3282,7 +3369,7 @@ paths:
       x-required-scopes:
         - machine-clients:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_environment
@@ -3384,7 +3471,7 @@ paths:
       x-required-scopes:
         - machine-events:ack
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_environment
@@ -3475,7 +3562,7 @@ paths:
           $ref: "#/components/responses/NotFound"
     post:
       operationId: createCustomerEndpoint
-      summary: Create an inactive customer endpoint and reveal its signing secret once
+      summary: Create an active 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
@@ -3491,7 +3578,7 @@ paths:
       x-required-scopes:
         - messages:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_environment
@@ -3516,7 +3603,7 @@ paths:
                 externalValue: ../fixtures/core-v1/requests/create-customer-endpoint.json
       responses:
         "201":
-          description: Newly created unverified endpoint and its one-time signing secret.
+          description: Newly active endpoint, recorded signed ping result, and its one-time signing secret.
           headers:
             WhooshBang-Diagnostic-Id:
               $ref: "#/components/headers/DiagnosticId"
@@ -3585,7 +3672,7 @@ paths:
       - $ref: "#/components/parameters/CustomerEndpointId"
     post:
       operationId: verifyCustomerEndpoint
-      summary: Send a signed challenge and activate the endpoint only after a signed echo
+      summary: Send a signed test ping and record whether the receiver returns 2xx
       tags:
         - Customer endpoints
       security:
@@ -3630,7 +3717,7 @@ paths:
       x-required-scopes:
         - messages:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_environment
@@ -3908,7 +3995,7 @@ paths:
       x-required-scopes:
         - connections:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_environment
@@ -4225,7 +4312,7 @@ paths:
       x-required-scopes:
         - connections:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_environment
@@ -4787,7 +4874,7 @@ paths:
       x-required-scopes:
         - connections:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_environment
@@ -5429,7 +5516,7 @@ paths:
       x-required-scopes:
         - subscriptions:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_project_environment
@@ -5735,7 +5822,7 @@ paths:
       x-required-scopes:
         - subscriptions:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_project_environment
@@ -5840,7 +5927,7 @@ paths:
             environment asked about. Combines with every other filter, so `q`
             searches within the group.
           schema:
-            $ref: "../schemas/whooshbang-v1.schema.json#/$defs/DeveloperKey"
+            $ref: "../schemas/whooshbang-v1.schema.json#/$defs/GroupKey"
         - name: created_after
           in: query
           required: false
@@ -5895,7 +5982,7 @@ paths:
       x-required-scopes:
         - subscriptions:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_project_environment
@@ -6056,7 +6143,7 @@ paths:
       x-required-scopes:
         - subscriptions:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_project_environment
@@ -6099,10 +6186,7 @@ paths:
         in: path
         required: true
         schema:
-          type: string
-          minLength: 1
-          maxLength: 63
-          pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+          $ref: "../schemas/whooshbang-v1.schema.json#/$defs/GroupKey"
     get:
       operationId: getSubscriberGroup
       summary: Read one static subscriber group
@@ -6194,10 +6278,7 @@ paths:
         in: path
         required: true
         schema:
-          type: string
-          minLength: 1
-          maxLength: 63
-          pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+          $ref: "../schemas/whooshbang-v1.schema.json#/$defs/GroupKey"
     get:
       operationId: listSubscriberGroupMembers
       summary: List active membership generations with bounded pagination
@@ -6248,10 +6329,7 @@ paths:
         in: path
         required: true
         schema:
-          type: string
-          minLength: 1
-          maxLength: 63
-          pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+          $ref: "../schemas/whooshbang-v1.schema.json#/$defs/GroupKey"
       - name: subscriber_id
         in: path
         required: true
@@ -6310,10 +6388,7 @@ paths:
         in: path
         required: true
         schema:
-          type: string
-          minLength: 1
-          maxLength: 63
-          pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+          $ref: "../schemas/whooshbang-v1.schema.json#/$defs/GroupKey"
     post:
       operationId: createGroupBroadcast
       summary: Accept one durable broadcast at the group's current membership revision
@@ -6329,7 +6404,7 @@ paths:
       x-required-scopes:
         - messages:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_project_environment
@@ -6451,7 +6526,7 @@ paths:
       x-required-scopes:
         - subscriptions:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_organization
@@ -6633,7 +6708,7 @@ paths:
       x-required-scopes:
         - messages:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_organization
@@ -6683,18 +6758,25 @@ paths:
       - $ref: "#/components/parameters/MessageId"
     get:
       operationId: getMessageInEnvironment
+      x-notification-scopes: [notifications:self, notifications:team]
       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.
+        Notification grants can read only current operator recipients in their
+        audience: self means the signed-in person; team includes current
+        teammates with access to this project. Customer subscribers and retired
+        memberships are hidden with 404, including during a held poll.
       parameters:
         - $ref: "#/components/parameters/ResponseInspectionWait"
       tags:
         - Messages
       security:
         - clerkSession: []
-        - bearerGrant: []
+        - bearerGrant: [messages:read]
+        - bearerGrant: [notifications:self]
+        - bearerGrant: [notifications:team]
         - bearerOrganizationCredential: []
       x-required-scopes:
         - messages:read
@@ -6728,16 +6810,23 @@ paths:
       - $ref: "#/components/parameters/InteractionId"
     get:
       operationId: getInteractionInEnvironment
+      x-notification-scopes: [notifications:self, notifications:team]
       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.
+        Notification grants can read only current operator recipients in their
+        audience: self means the signed-in person; team includes current
+        teammates with access to this project. Customer subscribers and retired
+        memberships are hidden with 404, including during a held poll.
       parameters:
         - $ref: "#/components/parameters/ResponseInspectionWait"
       tags:
         - Messages
       security:
-        - bearerGrant: []
+        - bearerGrant: [messages:read]
+        - bearerGrant: [notifications:self]
+        - bearerGrant: [notifications:team]
         - bearerOrganizationCredential: []
       x-required-scopes:
         - messages:read
@@ -6883,7 +6972,7 @@ paths:
       x-required-scopes:
         - machine-clients:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_organization
@@ -6947,7 +7036,7 @@ paths:
       x-required-scopes:
         - machine-clients:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_environment
@@ -7057,7 +7146,7 @@ paths:
       x-required-scopes:
         - subscriptions:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_project_environment
@@ -7165,7 +7254,7 @@ paths:
             environment asked about. Combines with every other filter, so `q`
             searches within the group.
           schema:
-            $ref: "../schemas/whooshbang-v1.schema.json#/$defs/DeveloperKey"
+            $ref: "../schemas/whooshbang-v1.schema.json#/$defs/GroupKey"
         - name: created_after
           in: query
           required: false
@@ -7225,7 +7314,7 @@ paths:
       x-required-scopes:
         - subscriptions:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_project_environment
@@ -7508,7 +7597,7 @@ paths:
       x-required-scopes:
         - subscriptions:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_project_environment
@@ -7553,10 +7642,7 @@ paths:
         in: path
         required: true
         schema:
-          type: string
-          minLength: 1
-          maxLength: 63
-          pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+          $ref: "../schemas/whooshbang-v1.schema.json#/$defs/GroupKey"
     get:
       operationId: getSubscriberGroupInEnvironment
       summary: Read one static subscriber group in a named project environment
@@ -7669,10 +7755,7 @@ paths:
         in: path
         required: true
         schema:
-          type: string
-          minLength: 1
-          maxLength: 63
-          pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+          $ref: "../schemas/whooshbang-v1.schema.json#/$defs/GroupKey"
     get:
       operationId: listSubscriberGroupMembersInEnvironment
       summary: List active membership generations in a named project environment
@@ -7732,10 +7815,7 @@ paths:
         in: path
         required: true
         schema:
-          type: string
-          minLength: 1
-          maxLength: 63
-          pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+          $ref: "../schemas/whooshbang-v1.schema.json#/$defs/GroupKey"
       - name: subscriber_id
         in: path
         required: true
@@ -7810,10 +7890,7 @@ paths:
         in: path
         required: true
         schema:
-          type: string
-          minLength: 1
-          maxLength: 63
-          pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+          $ref: "../schemas/whooshbang-v1.schema.json#/$defs/GroupKey"
     post:
       operationId: createGroupBroadcastInEnvironment
       summary: Accept one durable broadcast in a named project environment
@@ -7832,7 +7909,7 @@ paths:
       x-required-scopes:
         - messages:write
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope:
           - authenticated_project_environment
@@ -8247,7 +8324,7 @@ paths:
         - bearerOrganizationCredential: []
       x-required-scopes: [machine-clients:write]
       x-idempotency:
-        required: true
+        required: false
         retention_seconds: 604800
         scope: [authenticated_environment, operation_id, key]
         equivalence: validated_request_after_documented_defaults
@@ -8315,6 +8392,395 @@ paths:
           $ref: "#/components/responses/Conflict"
         "429":
           $ref: "#/components/responses/RateLimited"
+  /v1/operator-messages:
+    post:
+      operationId: sendOperatorMessageWithCredential
+      summary: sendOperatorMessage
+      description: >-
+        Message a current teammate by name or operator ID. Personal callers may omit recipient or use
+        me. Shared credentials must name a recipient. Runtime machine credentials report
+        recipient_required for omitted or me; named operator sends are forbidden because runtime
+        authority remains subscriber-bound.
+      tags:
+        - Operators
+      security:
+        - bearerCredential: []
+      x-required-scopes:
+        - messages:write
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateOperatorMessageRequest"
+      responses:
+        "200":
+          description: Authorized result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OperatorMessageResult"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /v1/operators/broadcasts:
+    post:
+      operationId: broadcastOperatorsWithCredential
+      summary: broadcastOperators
+      description: >-
+        Membership-derived operator messaging. Only the authenticated human can manage personal
+        preferences.
+      tags:
+        - Operators
+      security:
+        - bearerCredential: []
+      x-required-scopes:
+        - messages:write
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateGroupBroadcastRequest"
+      responses:
+        "200":
+          description: Authorized result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OperatorBroadcast"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /v1/operators/broadcasts/{broadcast_id}:
+    get:
+      operationId: getOperatorBroadcastWithCredential
+      summary: getOperatorBroadcast
+      description: >-
+        Membership-derived operator messaging. Only the authenticated human can manage personal
+        preferences.
+      tags:
+        - Operators
+      security:
+        - bearerCredential: []
+      x-required-scopes:
+        - messages:read
+      parameters:
+        - name: broadcast_id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Authorized result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OperatorBroadcast"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /v1/customer-endpoints:
+    get:
+      operationId: listCustomerEndpointsWithCredential
+      summary: List safe customer-endpoint health metadata
+      tags:
+        - Customer endpoints
+      security:
+        - bearerCredential: []
+      x-required-scopes:
+        - messages:read
+      parameters:
+        - $ref: "#/components/parameters/ListAfterCursor"
+        - $ref: "#/components/parameters/ListPageLimit"
+        - $ref: "#/components/parameters/PageNumber"
+      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: createCustomerEndpointWithCredential
+      summary: Create an active customer endpoint and reveal its signing secret once
+      description: >-
+        Creates an active endpoint and sends a signed diagnostic ping. A 2xx acknowledges the ping; no
+        echo handshake is required. SSRF destination validation applies.
+      tags:
+        - Customer endpoints
+      security:
+        - bearerCredential: []
+      x-required-scopes:
+        - messages:write
+      x-idempotency:
+        required: false
+        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:
+        "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
+        "201":
+          description: Newly active endpoint, recorded signed ping result, 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
+        "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/customer-endpoints/{endpoint_id}:
+    parameters:
+      - $ref: "#/components/parameters/CustomerEndpointId"
+    get:
+      operationId: getCustomerEndpointWithCredential
+      summary: Read safe lifecycle and health metadata for one endpoint
+      tags:
+        - Customer endpoints
+      security:
+        - bearerCredential: []
+      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/customer-endpoints/{endpoint_id}/verify:
+    parameters:
+      - $ref: "#/components/parameters/CustomerEndpointId"
+    post:
+      operationId: verifyCustomerEndpointWithCredential
+      summary: Send a signed test ping and record whether the receiver returns 2xx
+      tags:
+        - Customer endpoints
+      security:
+        - bearerCredential: []
+      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/customer-endpoints/{endpoint_id}/rotate:
+    parameters:
+      - $ref: "#/components/parameters/CustomerEndpointId"
+    post:
+      operationId: rotateCustomerEndpointWithCredential
+      summary: Create a new signing version with bounded old/new overlap
+      tags:
+        - Customer endpoints
+      security:
+        - bearerCredential: []
+      x-required-scopes:
+        - messages:write
+      x-idempotency:
+        required: false
+        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:
+        "200":
+          description: Equivalent replay without another secret reveal.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CustomerEndpointMutationResult"
+        "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
+        "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/customer-endpoints/{endpoint_id}/{action}:
+    parameters:
+      - $ref: "#/components/parameters/CustomerEndpointId"
+      - name: action
+        in: path
+        required: true
+        schema:
+          type: string
+          enum:
+            - pause
+            - resume
+            - disable
+    post:
+      operationId: transitionCustomerEndpointWithCredential
+      summary: Pause, resume, or terminally disable an endpoint
+      tags:
+        - Customer endpoints
+      security:
+        - bearerCredential: []
+      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"
+      description: >-
+        Creates an active endpoint and sends a signed diagnostic ping. A 2xx acknowledges the ping; no
+        echo handshake is required. SSRF destination validation applies.
+  /v1/customer-endpoints/{endpoint_id}/attempts:
+    parameters:
+      - $ref: "#/components/parameters/CustomerEndpointId"
+    get:
+      operationId: listCustomerEndpointAttemptsWithCredential
+      summary: Inspect protected content-free delivery diagnostics
+      tags:
+        - Customer endpoints
+      security:
+        - bearerCredential: []
+      x-required-scopes:
+        - messages:read
+      parameters:
+        - $ref: "#/components/parameters/ListAfterCursor"
+        - $ref: "#/components/parameters/ListPageLimit"
+        - $ref: "#/components/parameters/PageNumber"
+      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"
 components:
   securitySchemes:
     clerkSession:
@@ -8390,9 +8856,11 @@ components:
     IdempotencyKey:
       name: Idempotency-Key
       in: header
-      required: true
+      required: false
       description: |
-        Visible ASCII key retained for seven days from first acceptance.
+        Optional visible ASCII key retained for seven days from first acceptance.
+        A retry with the same key returns the original result and never acts twice.
+        Without a key each request is new.
         Equivalent replay returns the original status and logical resource;
         materially different validated input returns `idempotency_conflict`.
       schema:
@@ -8754,6 +9222,12 @@ components:
       $ref: "../schemas/whooshbang-v1.schema.json#/$defs/BillingProjectSlots"
     AssignBillingProjectSlotsRequest:
       $ref: "../schemas/whooshbang-v1.schema.json#/$defs/AssignBillingProjectSlotsRequest"
+    BillingPromotions:
+      $ref: "../schemas/whooshbang-v1.schema.json#/$defs/BillingPromotions"
+    BillingPromotion:
+      $ref: "../schemas/whooshbang-v1.schema.json#/$defs/BillingPromotion"
+    RedeemBillingPromotionRequest:
+      $ref: "../schemas/whooshbang-v1.schema.json#/$defs/RedeemBillingPromotionRequest"
     BillingEntitlements:
       $ref: "../schemas/whooshbang-v1.schema.json#/$defs/BillingEntitlements"
     SubscriptionSelection: