@whooshbang/contracts 2.4.0 → 2.6.0

package/openapi/generated/whooshbang-v1.bundle.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.1",
   "info": {
     "title": "WhooshBang API",
-    "version": "2.4.0",
+    "version": "2.6.0",
     "description": "The V1 contract for human organization/project administration, project-scoped\nsubscription links, and asynchronous text messages. A Clerk session selects\none organization for administration. A project credential selects one organization,\nproject, and `test` or `live` environment for product operations; request\nbodies cannot override either authenticated scope.\n\nA person's OAuth grant selects one organization and carries scopes, but no\nproject. It names the project and environment it acts in through the URL\npath, on the environment-scoped form of each operation; the service checks\nthat path against the granting person's membership on every call. The flat\nforms remain credential-only and are unchanged.\n\nResource identifiers are opaque and are not authorization. Reads outside the\ncredential scope return the same `404` shape as absent resources. Provider\ncredentials, raw Telegram identity, and protected provider responses are\nnever part of this API.\n",
     "termsOfService": "https://flowxo.com/terms",
     "contact": {
@@ -524,6 +524,92 @@
         }
       }
     },
+    "/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\nand promotion codes it redeemed, with what remains and when each ends. Promotional value has no cash\nvalue, is never refunded and cannot move to another organization.\n",
+        "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.\nEvery code that cannot be redeemed (mistyped, ended, fully used, not offered to this organization, or not\ncombinable with a promotion it already holds) receives the same `resource_not_found` answer. Repeated\nrefusals are rate limited per organization; wait for `Retry-After`. Reuse the same idempotency key after\nan uncertain response: it can never redeem twice.\n",
+        "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",
@@ -2311,7 +2397,7 @@
         "x-required-scopes": ["projects:write"],
         "x-organization-membership": "required",
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_organization", "operation_id", "key"],
           "equivalence": "validated_request",
@@ -2984,7 +3070,7 @@
         "security": [{ "bearerCredential": [] }],
         "x-required-scopes": ["subscriptions:write"],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_environment", "operation_id", "key"],
           "equivalence": "validated_request_after_documented_defaults",
@@ -3139,7 +3225,7 @@
         "security": [{ "bearerCredential": [] }],
         "x-required-scopes": ["subscriptions:write"],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_environment", "operation_id", "key"],
           "equivalence": "validated_request_after_documented_defaults",
@@ -3220,7 +3306,7 @@
         ],
         "x-required-scopes": ["messages:write"],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_environment", "operation_id", "key"],
           "equivalence": "canonical_rgba_png_after_validation",
@@ -3342,7 +3428,7 @@
           "bound_subscriber"
         ],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_environment", "operation_id", "key"],
           "equivalence": "validated_request_after_documented_defaults",
@@ -3770,7 +3856,7 @@
         "security": [{ "bearerCredential": [] }],
         "x-required-scopes": ["messages:write"],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_environment", "operation_id", "key"],
           "equivalence": "validated_request_after_documented_defaults",
@@ -3876,7 +3962,7 @@
         "security": [{ "bearerCredential": [] }],
         "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",
@@ -4013,7 +4099,7 @@
         "security": [{ "bearerCredential": [] }],
         "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",
@@ -4121,7 +4207,7 @@
         "security": [{ "bearerCredential": [] }],
         "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",
@@ -4179,7 +4265,7 @@
         "security": [{ "bearerCredential": [] }],
         "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",
@@ -4342,7 +4428,7 @@
         "security": [{ "machineCredential": [] }],
         "x-required-scopes": ["machine-events:ack"],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_environment", "operation_id", "key"],
           "equivalence": "validated_request_after_documented_defaults",
@@ -4513,7 +4599,7 @@
       },
       "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.\nThe initial response includes the new signing secret. An equivalent\nidempotent replay returns the same logical endpoint without the secret;\ndifferent input for the same key returns `idempotency_conflict`.\n",
         "tags": ["Customer endpoints"],
         "security": [
@@ -4524,7 +4610,7 @@
         ],
         "x-required-scopes": ["messages:write"],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_environment", "operation_id", "key"],
           "equivalence": "final_normalized_url_and_validated_request",
@@ -4593,7 +4679,7 @@
             }
           },
           "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"
@@ -4680,7 +4766,7 @@
       ],
       "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": [
           { "clerkSession": [] },
@@ -4724,7 +4810,7 @@
         ],
         "x-required-scopes": ["messages:write"],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_environment", "operation_id", "key"],
           "equivalence": "endpoint_and_validated_request",
@@ -5072,7 +5158,7 @@
         ],
         "x-required-scopes": ["connections:write"],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_environment", "operation_id", "key"],
           "equivalence": "validated_request",
@@ -5563,7 +5649,7 @@
         ],
         "x-required-scopes": ["connections:write"],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_environment", "operation_id", "key"],
           "equivalence": "selected_connection",
@@ -6173,7 +6259,7 @@
         ],
         "x-required-scopes": ["connections:write"],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_environment", "operation_id", "key"],
           "equivalence": "exact_request_body",
@@ -6959,7 +7045,7 @@
         "security": [{ "bearerCredential": [] }],
         "x-required-scopes": ["subscriptions:write"],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_project_environment", "operation_id", "key"],
           "equivalence": "validated_request",
@@ -7387,7 +7473,7 @@
         "security": [{ "bearerCredential": [] }],
         "x-required-scopes": ["subscriptions:write"],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_project_environment", "operation_id", "key"],
           "equivalence": "validated_request",
@@ -7520,7 +7606,7 @@
             "in": "query",
             "required": false,
             "description": "Only current members of the static group with this key, in the\nenvironment asked about. Combines with every other filter, so `q`\nsearches within the group.\n",
-            "schema": { "$ref": "#/components/schemas/DeveloperKey" }
+            "schema": { "$ref": "#/components/schemas/GroupKey" }
           },
           {
             "name": "created_after",
@@ -7595,7 +7681,7 @@
         "security": [{ "bearerCredential": [] }],
         "x-required-scopes": ["subscriptions:write"],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_project_environment", "operation_id", "key"],
           "equivalence": "validated_request",
@@ -7790,7 +7876,7 @@
         "security": [{ "bearerCredential": [] }],
         "x-required-scopes": ["subscriptions:write"],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_project_environment", "operation_id", "key"],
           "equivalence": "validated_request",
@@ -7856,12 +7942,7 @@
           "name": "group_key",
           "in": "path",
           "required": true,
-          "schema": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 63,
-            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
-          }
+          "schema": { "$ref": "#/components/schemas/GroupKey" }
         }
       ],
       "get": {
@@ -7952,12 +8033,7 @@
           "name": "group_key",
           "in": "path",
           "required": true,
-          "schema": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 63,
-            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
-          }
+          "schema": { "$ref": "#/components/schemas/GroupKey" }
         }
       ],
       "get": {
@@ -8039,12 +8115,7 @@
           "name": "group_key",
           "in": "path",
           "required": true,
-          "schema": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 63,
-            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
-          }
+          "schema": { "$ref": "#/components/schemas/GroupKey" }
         },
         {
           "name": "subscriber_id",
@@ -8114,12 +8185,7 @@
           "name": "group_key",
           "in": "path",
           "required": true,
-          "schema": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 63,
-            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
-          }
+          "schema": { "$ref": "#/components/schemas/GroupKey" }
         }
       ],
       "post": {
@@ -8130,7 +8196,7 @@
         "security": [{ "bearerCredential": [] }],
         "x-required-scopes": ["messages:write"],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_project_environment", "operation_id", "key"],
           "equivalence": "validated_request_and_group_key",
@@ -8406,7 +8472,7 @@
         ],
         "x-required-scopes": ["subscriptions:write"],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_organization", "operation_id", "key"],
           "equivalence": "validated_request",
@@ -8655,7 +8721,7 @@
         ],
         "x-required-scopes": ["messages:write"],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_organization", "operation_id", "key"],
           "equivalence": "validated_request",
@@ -8735,15 +8801,18 @@
       ],
       "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\nlong poll. Inspection acknowledges, consumes, retries, and replays\nnothing.\n",
+        "description": "The environment-scoped form of `getMessage`, including the same bounded\nlong poll. Inspection acknowledges, consumes, retries, and replays\nnothing.\nNotification grants can read only current operator recipients in their\naudience: self means the signed-in person; team includes current\nteammates with access to this project. Customer subscribers and retired\nmemberships are hidden with 404, including during a held poll.\n",
         "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"],
@@ -8810,14 +8879,17 @@
       ],
       "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\nbounded long poll and the same retained-answer semantics.\n",
+        "description": "The environment-scoped form of `getInteraction`, including the same\nbounded long poll and the same retained-answer semantics.\nNotification grants can read only current operator recipients in their\naudience: self means the signed-in person; team includes current\nteammates with access to this project. Customer subscribers and retired\nmemberships are hidden with 404, including during a held poll.\n",
         "parameters": [
           { "$ref": "#/components/parameters/ResponseInspectionWait" }
         ],
         "tags": ["Messages"],
         "security": [
-          { "bearerGrant": [] },
+          { "bearerGrant": ["messages:read"] },
+          { "bearerGrant": ["notifications:self"] },
+          { "bearerGrant": ["notifications:team"] },
           { "bearerOrganizationCredential": [] }
         ],
         "x-required-scopes": ["messages:read"],
@@ -9008,7 +9080,7 @@
         ],
         "x-required-scopes": ["machine-clients:write"],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_organization", "operation_id", "key"],
           "equivalence": "validated_request",
@@ -9089,7 +9161,7 @@
         ],
         "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",
@@ -9297,7 +9369,7 @@
         ],
         "x-required-scopes": ["subscriptions:write"],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_project_environment", "operation_id", "key"],
           "equivalence": "validated_request",
@@ -9439,7 +9511,7 @@
             "in": "query",
             "required": false,
             "description": "Only current members of the static group with this key, in the\nenvironment asked about. Combines with every other filter, so `q`\nsearches within the group.\n",
-            "schema": { "$ref": "#/components/schemas/DeveloperKey" }
+            "schema": { "$ref": "#/components/schemas/GroupKey" }
           },
           {
             "name": "created_after",
@@ -9519,7 +9591,7 @@
         ],
         "x-required-scopes": ["subscriptions:write"],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_project_environment", "operation_id", "key"],
           "equivalence": "validated_request",
@@ -9834,7 +9906,7 @@
         ],
         "x-required-scopes": ["subscriptions:write"],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_project_environment", "operation_id", "key"],
           "equivalence": "validated_request",
@@ -9902,12 +9974,7 @@
           "name": "group_key",
           "in": "path",
           "required": true,
-          "schema": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 63,
-            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
-          }
+          "schema": { "$ref": "#/components/schemas/GroupKey" }
         }
       ],
       "get": {
@@ -10018,12 +10085,7 @@
           "name": "group_key",
           "in": "path",
           "required": true,
-          "schema": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 63,
-            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
-          }
+          "schema": { "$ref": "#/components/schemas/GroupKey" }
         }
       ],
       "get": {
@@ -10113,12 +10175,7 @@
           "name": "group_key",
           "in": "path",
           "required": true,
-          "schema": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 63,
-            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
-          }
+          "schema": { "$ref": "#/components/schemas/GroupKey" }
         },
         {
           "name": "subscriber_id",
@@ -10202,12 +10259,7 @@
           "name": "group_key",
           "in": "path",
           "required": true,
-          "schema": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 63,
-            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
-          }
+          "schema": { "$ref": "#/components/schemas/GroupKey" }
         }
       ],
       "post": {
@@ -10223,7 +10275,7 @@
         ],
         "x-required-scopes": ["messages:write"],
         "x-idempotency": {
-          "required": true,
+          "required": false,
           "retention_seconds": 604800,
           "scope": ["authenticated_project_environment", "operation_id", "key"],
           "equivalence": "validated_request_and_group_key",
@@ -10725,7 +10777,7 @@
         ],
         "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",
@@ -10799,74 +10851,591 @@
           "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\none WhooshBang organization. Every administration operation rechecks the\nprojected organization membership; session identity never selects a project\nor environment from request data.\n"
-      },
-      "bearerGrant": {
-        "type": "http",
-        "scheme": "bearer",
-        "bearerFormat": "OAuth 2.0 access token",
-        "description": "An access token issued by the WhooshBang authorization server for one\nconsenting organization member. It selects exactly one organization and carries\nthe scopes that member consented to, and never a project: an operation\nnames its project and environment in the path, and the service checks\nboth against the granting person's membership before acting. A project\ncredential can name no project but its own; an organization credential names\none per call the same way this does.\n"
-      },
-      "bearerOrganizationCredential": {
-        "type": "http",
-        "scheme": "bearer",
-        "bearerFormat": "wb_oc1.ocred_<16-byte-base64url>.<32-byte-base64url-secret>",
-        "description": "Selects exactly one organization and nothing below it. It names no project\nand no environment, so it authenticates only operations whose path does,\nand its authority there is the intersection of its scopes with the\nproject-credential vocabulary — never wider than a project credential\nwould have been for the same project environment. A path naming a\nproject outside its organization is refused with `credential_organization_mismatch`\nrather than a bare scope failure. `organization:read` is the one scope it can\nhold that a project credential cannot, and it authorizes only the\norganization's project directory: listing the organization's projects and reading\none, which is the organization-wide question a project credential cannot ask\nand the reason a `--project <slug>` selector can work at all. It is\nrequired *in addition to* each of those operations' own\n`x-required-scopes`, never instead of them.\nCredentials cannot be read after creation.\n"
-      },
-      "bearerCredential": {
-        "type": "http",
-        "scheme": "bearer",
-        "bearerFormat": "wb_pc1.pcred_<16-byte-base64url>.<32-byte-base64url-secret>",
-        "description": "Selects exactly one organization, project, and `test` or `live` environment.\nCredentials cannot be read after creation. Except for explicitly\nsynthetic creation/rotation reveal fixtures, complete bearer values\nmust never appear in fixtures, errors, logs, metrics, or inspection\nsurfaces.\n"
-      },
-      "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\nproject/environment, machine client, notifier, subscriber, binding, and\nevent stream. Project credentials cannot use machine-only endpoints.\nRevoked credentials fail before resource lookup.\n"
-      },
-      "recipientSessionCapability": {
-        "type": "apiKey",
-        "in": "header",
-        "name": "WhooshBang-Recipient-Capability",
-        "description": "A creation-only, short-lived capability bound server-side to one exact\norganization, project, environment, subscriber, configuration revision,\npresenting origin, and registered return destination. It is accepted\nonly on the `/v1/recipient-session` browser surface and never as bearer\nauthority on an ordinary application route.\n"
+    },
+    "/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" }
+        }
       }
     },
-    "parameters": {
-      "IdempotencyKey": {
-        "name": "Idempotency-Key",
-        "in": "header",
-        "required": true,
-        "description": "Visible ASCII key retained for seven days from first acceptance.\nEquivalent replay returns the original status and logical resource;\nmaterially different validated input returns `idempotency_conflict`.\n",
-        "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.",
+    "/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": {
+                    "value": {
+                      "items": [
+                        {
+                          "id": "endpoint_11111111111111111111111111111111",
+                          "project_id": "project_synthetic_alpha",
+                          "environment_id": "environment_test_synthetic_alpha",
+                          "environment": "test",
+                          "status": "active",
+                          "verification_status": "verified",
+                          "event_types": [
+                            "interaction.received",
+                            "message.delivered"
+                          ],
+                          "secret_version": 2,
+                          "health": "failing",
+                          "created_at": "2026-08-06T12:00:00.000Z",
+                          "updated_at": "2026-08-06T14:00:00.000Z",
+                          "verification_attempted_at": "2026-08-06T12:05:00.000Z",
+                          "verified_at": "2026-08-06T12:05:00.000Z",
+                          "rotated_at": "2026-08-06T13:00:00.000Z",
+                          "last_success_at": "2026-08-06T13:30:00.000Z",
+                          "last_failure": {
+                            "at": "2026-08-06T14:00:00.000Z",
+                            "category": "network_failure"
+                          },
+                          "diagnostic_id": "diag_endpoint_list_001"
+                        }
+                      ],
+                      "total": 1,
+                      "page": 1,
+                      "page_size": 50
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "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": {
+                  "value": {
+                    "url": "https://events.example.com/whooshbang",
+                    "event_types": [
+                      "interaction.received",
+                      "message.delivered"
+                    ],
+                    "local_test": false
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Equivalent replay returning safe endpoint metadata without the secret.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CustomerEndpointMutationResult"
+                },
+                "examples": {
+                  "replayed": {
+                    "value": {
+                      "endpoint": {
+                        "id": "endpoint_11111111111111111111111111111111",
+                        "project_id": "project_synthetic_alpha",
+                        "environment_id": "environment_test_synthetic_alpha",
+                        "environment": "test",
+                        "status": "unverified",
+                        "verification_status": "pending",
+                        "event_types": [
+                          "interaction.received",
+                          "message.delivered"
+                        ],
+                        "secret_version": 1,
+                        "health": "never_delivered",
+                        "created_at": "2026-08-06T12:00:00.000Z",
+                        "updated_at": "2026-08-06T12:00:00.000Z",
+                        "diagnostic_id": "diag_endpoint_replay_001"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "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": {
+                    "value": {
+                      "endpoint": {
+                        "id": "endpoint_11111111111111111111111111111111",
+                        "project_id": "project_synthetic_alpha",
+                        "environment_id": "environment_test_synthetic_alpha",
+                        "environment": "test",
+                        "status": "unverified",
+                        "verification_status": "pending",
+                        "event_types": [
+                          "interaction.received",
+                          "message.delivered"
+                        ],
+                        "secret_version": 1,
+                        "health": "never_delivered",
+                        "created_at": "2026-08-06T12:00:00.000Z",
+                        "updated_at": "2026-08-06T12:00:00.000Z",
+                        "diagnostic_id": "diag_endpoint_create_001"
+                      },
+                      "secret": "whsec_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8="
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "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": { "value": { "overlap_seconds": 3600 } } }
+            }
+          }
+        },
+        "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": {
+                    "value": {
+                      "endpoint": {
+                        "id": "endpoint_11111111111111111111111111111111",
+                        "project_id": "project_synthetic_alpha",
+                        "environment_id": "environment_test_synthetic_alpha",
+                        "environment": "test",
+                        "status": "active",
+                        "verification_status": "verified",
+                        "event_types": [
+                          "interaction.received",
+                          "message.delivered"
+                        ],
+                        "secret_version": 2,
+                        "health": "healthy",
+                        "created_at": "2026-08-06T12:00:00.000Z",
+                        "updated_at": "2026-08-06T13:00:00.000Z",
+                        "verification_attempted_at": "2026-08-06T12:05:00.000Z",
+                        "verified_at": "2026-08-06T12:05:00.000Z",
+                        "rotated_at": "2026-08-06T13:00:00.000Z",
+                        "last_success_at": "2026-08-06T12:30:00.000Z",
+                        "diagnostic_id": "diag_endpoint_rotate_001"
+                      },
+                      "secret": "whsec_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "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": {
+                    "value": {
+                      "endpoint_id": "endpoint_11111111111111111111111111111111",
+                      "attempts": [
+                        {
+                          "id": "ceattempt_11111111111111111111111111111111",
+                          "event_id": "evt_interaction_received_synthetic",
+                          "attempt": 1,
+                          "status": "terminal_failed",
+                          "diagnostic_code": "network_failure",
+                          "started_at": "2026-08-06T14:00:00.000Z",
+                          "completed_at": "2026-08-06T14:00:01.000Z",
+                          "created_at": "2026-08-06T14:00:00.000Z"
+                        }
+                      ],
+                      "total": 1,
+                      "page": 1,
+                      "page_size": 50
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "401": { "$ref": "#/components/responses/Unauthorized" },
+          "403": { "$ref": "#/components/responses/Forbidden" },
+          "404": { "$ref": "#/components/responses/NotFound" }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "clerkSession": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "Clerk session JWT",
+        "description": "A verified human session whose active Clerk organization selects exactly\none WhooshBang organization. Every administration operation rechecks the\nprojected organization membership; session identity never selects a project\nor environment from request data.\n"
+      },
+      "bearerGrant": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "OAuth 2.0 access token",
+        "description": "An access token issued by the WhooshBang authorization server for one\nconsenting organization member. It selects exactly one organization and carries\nthe scopes that member consented to, and never a project: an operation\nnames its project and environment in the path, and the service checks\nboth against the granting person's membership before acting. A project\ncredential can name no project but its own; an organization credential names\none per call the same way this does.\n"
+      },
+      "bearerOrganizationCredential": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "wb_oc1.ocred_<16-byte-base64url>.<32-byte-base64url-secret>",
+        "description": "Selects exactly one organization and nothing below it. It names no project\nand no environment, so it authenticates only operations whose path does,\nand its authority there is the intersection of its scopes with the\nproject-credential vocabulary — never wider than a project credential\nwould have been for the same project environment. A path naming a\nproject outside its organization is refused with `credential_organization_mismatch`\nrather than a bare scope failure. `organization:read` is the one scope it can\nhold that a project credential cannot, and it authorizes only the\norganization's project directory: listing the organization's projects and reading\none, which is the organization-wide question a project credential cannot ask\nand the reason a `--project <slug>` selector can work at all. It is\nrequired *in addition to* each of those operations' own\n`x-required-scopes`, never instead of them.\nCredentials cannot be read after creation.\n"
+      },
+      "bearerCredential": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "wb_pc1.pcred_<16-byte-base64url>.<32-byte-base64url-secret>",
+        "description": "Selects exactly one organization, project, and `test` or `live` environment.\nCredentials cannot be read after creation. Except for explicitly\nsynthetic creation/rotation reveal fixtures, complete bearer values\nmust never appear in fixtures, errors, logs, metrics, or inspection\nsurfaces.\n"
+      },
+      "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\nproject/environment, machine client, notifier, subscriber, binding, and\nevent stream. Project credentials cannot use machine-only endpoints.\nRevoked credentials fail before resource lookup.\n"
+      },
+      "recipientSessionCapability": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "WhooshBang-Recipient-Capability",
+        "description": "A creation-only, short-lived capability bound server-side to one exact\norganization, project, environment, subscriber, configuration revision,\npresenting origin, and registered return destination. It is accepted\nonly on the `/v1/recipient-session` browser surface and never as bearer\nauthority on an ordinary application route.\n"
+      }
+    },
+    "parameters": {
+      "IdempotencyKey": {
+        "name": "Idempotency-Key",
+        "in": "header",
+        "required": false,
+        "description": "Optional visible ASCII key retained for seven days from first acceptance.\nA retry with the same key returns the original result and never acts twice.\nWithout a key each request is new.\nEquivalent replay returns the original status and logical resource;\nmaterially different validated input returns `idempotency_conflict`.\n",
+        "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": {
@@ -11218,13 +11787,13 @@
       "CreateOperatorMessageRequest": {
         "type": "object",
         "description": "Send to a teammate by exact name or operator ID, or use me. Omitted recipient means the verified authenticated human only. Shared and service credentials must name a recipient. Preferred channel, service-email billing and marketing restrictions still apply.",
-        "required": ["content"],
+        "required": [],
         "properties": {
           "recipient": { "type": "string", "minLength": 1, "maxLength": 128 },
-          "content": { "$ref": "#/components/schemas/MessageContent" },
+          "content": { "$ref": "#/components/schemas/MessageContentInput" },
           "expires_at": {
             "$ref": "#/components/schemas/Timestamp",
-            "description": "Optional server-authoritative expiry no more than 24 hours after acceptance."
+            "description": "Optional server-authoritative expiry after acceptance, through year 9999. Omit for 24 hours."
           },
           "correlation_id": {
             "type": "string",
@@ -11241,7 +11810,31 @@
             "description": "Omitted means service. Marketing refuses service-only bindings before charging and at every delayed dispatch."
           }
         },
-        "additionalProperties": false
+        "additionalProperties": false,
+        "allOf": [
+          {
+            "anyOf": [
+              {
+                "required": ["content"],
+                "properties": {
+                  "content": {
+                    "$ref": "#/components/schemas/MessageContentInput"
+                  }
+                },
+                "additionalProperties": true
+              },
+              {
+                "required": ["interaction"],
+                "properties": {
+                  "interaction": {
+                    "$ref": "#/components/schemas/InteractionSendRequest"
+                  }
+                },
+                "additionalProperties": true
+              }
+            ]
+          }
+        ]
       },
       "OperatorMessageResult": {
         "type": "object",
@@ -12865,6 +13458,202 @@
         "additionalProperties": false,
         "description": "Replace the requested active project selection with owned, active projects within current paid capacity. An empty selection releases all slots."
       },
+      "BillingPromotions": {
+        "type": "object",
+        "required": [
+          "promotional_credit_usd",
+          "free_shared_emails",
+          "branding_removed_until",
+          "promotions"
+        ],
+        "properties": {
+          "promotional_credit_usd": {
+            "type": "string",
+            "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+            "maxLength": 40,
+            "description": "Unexpired promotional message credit available now."
+          },
+          "free_shared_emails": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 2147483647,
+            "description": "Unexpired free shared emails available now."
+          },
+          "branding_removed_until": {
+            "anyOf": [
+              { "type": "string", "format": "date-time" },
+              { "type": "null" }
+            ],
+            "description": "When the latest active branding promotion ends, if one is active."
+          },
+          "promotions": {
+            "type": "array",
+            "items": { "$ref": "#/components/schemas/BillingPromotion" },
+            "maxItems": 200
+          }
+        },
+        "additionalProperties": false,
+        "description": "An organization's promotions: rewards WhooshBang gave it and promotion codes it redeemed, newest first."
+      },
+      "BillingPromotion": {
+        "type": "object",
+        "required": [
+          "id",
+          "source",
+          "name",
+          "status",
+          "starts_at",
+          "ends_at",
+          "ended_at",
+          "benefit"
+        ],
+        "properties": {
+          "id": { "type": "string", "pattern": "^grn_[0-9a-z]{26}$" },
+          "source": {
+            "type": "string",
+            "enum": ["whooshbang", "code"],
+            "description": "`whooshbang` for a reward WhooshBang gave the organization directly; `code` for a promotion code the organization redeemed."
+          },
+          "name": {
+            "anyOf": [
+              { "type": "string", "minLength": 1, "maxLength": 120 },
+              { "type": "null" }
+            ],
+            "description": "The promotion's name for a redeemed code. Null for a direct reward."
+          },
+          "status": {
+            "type": "string",
+            "enum": ["active", "pending", "expired", "used", "revoked"],
+            "description": "`pending` is a credit pack discount carried by a payment still waiting for the customer's bank; it is not available to another purchase. `used` applies only to a discount that has been applied to a purchase or put on a plan. `revoked` means WhooshBang withdrew what remained."
+          },
+          "starts_at": { "type": "string", "format": "date-time" },
+          "ends_at": {
+            "anyOf": [
+              { "type": "string", "format": "date-time" },
+              { "type": "null" }
+            ],
+            "description": "When the benefit stops. Null for a discount, which ends when it is used or, for a plan discount, after its months."
+          },
+          "ended_at": {
+            "anyOf": [
+              { "type": "string", "format": "date-time" },
+              { "type": "null" }
+            ],
+            "description": "When the promotion was used or withdrawn, if it was."
+          },
+          "benefit": {
+            "oneOf": [
+              {
+                "type": "object",
+                "required": ["kind", "credit_usd", "remaining_usd"],
+                "properties": {
+                  "kind": { "const": "message_credit" },
+                  "credit_usd": {
+                    "type": "string",
+                    "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+                    "maxLength": 40
+                  },
+                  "remaining_usd": {
+                    "type": "string",
+                    "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+                    "maxLength": 40
+                  }
+                },
+                "additionalProperties": false,
+                "description": "Promotional credit for messages. Spent before purchased, bonus and welcome credit; it never pays the shared-email charge."
+              },
+              {
+                "type": "object",
+                "required": ["kind", "shared_emails", "remaining"],
+                "properties": {
+                  "kind": { "const": "shared_emails" },
+                  "shared_emails": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 1000000
+                  },
+                  "remaining": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 1000000
+                  }
+                },
+                "additionalProperties": false,
+                "description": "Emails through WhooshBang's shared email service with no shared-email charge. The message itself is still paid for."
+              },
+              {
+                "type": "object",
+                "required": ["kind"],
+                "properties": { "kind": { "const": "branding" } },
+                "additionalProperties": false,
+                "description": "WhooshBang branding can be removed from recipient messages until ends_at."
+              },
+              {
+                "type": "object",
+                "required": [
+                  "kind",
+                  "applies_to",
+                  "percent_off",
+                  "amount_off_usd",
+                  "duration",
+                  "months"
+                ],
+                "properties": {
+                  "kind": { "const": "discount" },
+                  "applies_to": {
+                    "type": "string",
+                    "enum": ["credit_packs", "subscriptions"]
+                  },
+                  "percent_off": {
+                    "anyOf": [
+                      { "type": "integer", "minimum": 1, "maximum": 90 },
+                      { "type": "null" }
+                    ]
+                  },
+                  "amount_off_usd": {
+                    "anyOf": [
+                      {
+                        "type": "string",
+                        "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+                        "maxLength": 40
+                      },
+                      { "type": "null" }
+                    ]
+                  },
+                  "duration": {
+                    "type": "string",
+                    "enum": ["once", "repeating"]
+                  },
+                  "months": {
+                    "anyOf": [
+                      { "type": "integer", "minimum": 1, "maximum": 12 },
+                      { "type": "null" }
+                    ]
+                  }
+                },
+                "additionalProperties": false,
+                "description": "Money off the next credit pack, or off plan and add-on charges for one charge or a number of months."
+              }
+            ]
+          }
+        },
+        "additionalProperties": false,
+        "description": "One promotion an organization holds. Promotional value has no cash value, is never refunded and cannot move to another organization."
+      },
+      "RedeemBillingPromotionRequest": {
+        "type": "object",
+        "required": ["code"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "minLength": 4,
+            "maxLength": 64,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9 _-]*$",
+            "description": "The promotion code. Case, spaces, hyphens and underscores are ignored."
+          }
+        },
+        "additionalProperties": false
+      },
       "BillingEntitlements": {
         "type": "object",
         "required": [
@@ -13029,6 +13818,8 @@
           "monthly_price_usd",
           "charge_now_usd",
           "unused_time_credit_usd",
+          "promotion",
+          "renewal_promotion",
           "effective_at",
           "expires_at",
           "client_secret",
@@ -13084,6 +13875,85 @@
             ],
             "description": "Compatibility field: new upgrades return 0.000000; starts and boundary changes return null. Historical quotes can retain their recorded unused-time credit. No new automatic unused-time refunds or offsets."
           },
+          "promotion": {
+            "anyOf": [
+              {
+                "type": "object",
+                "required": [
+                  "percent_off",
+                  "duration",
+                  "months",
+                  "discount_usd"
+                ],
+                "properties": {
+                  "percent_off": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 90
+                  },
+                  "duration": {
+                    "type": "string",
+                    "enum": ["once", "repeating"]
+                  },
+                  "months": {
+                    "anyOf": [
+                      { "type": "integer", "minimum": 1, "maximum": 12 },
+                      { "type": "null" }
+                    ]
+                  },
+                  "discount_usd": {
+                    "type": "string",
+                    "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+                    "maxLength": 40,
+                    "description": "What the promotion takes off charge_now_usd."
+                  }
+                },
+                "additionalProperties": false
+              },
+              { "type": "null" }
+            ],
+            "description": "A promotion code's plan discount applied to this first plan or add-on purchase: charge_now_usd is already reduced by it, and the monthly charges keep it for its months. Null when no plan discount applies."
+          },
+          "renewal_promotion": {
+            "anyOf": [
+              {
+                "type": "object",
+                "required": [
+                  "percent_off",
+                  "duration",
+                  "renewal_price_usd",
+                  "ends_at"
+                ],
+                "properties": {
+                  "percent_off": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 90
+                  },
+                  "duration": {
+                    "type": "string",
+                    "enum": ["once", "repeating"]
+                  },
+                  "renewal_price_usd": {
+                    "type": "string",
+                    "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+                    "maxLength": 40,
+                    "description": "What the next monthly charge for this selection comes to with the promotion: monthly_price_usd less its percentage."
+                  },
+                  "ends_at": {
+                    "anyOf": [
+                      { "type": "string", "format": "date-time" },
+                      { "type": "null" }
+                    ],
+                    "description": "When a repeating promotion stops applying. Null for a once promotion, which applies to the next monthly charge only."
+                  }
+                },
+                "additionalProperties": false
+              },
+              { "type": "null" }
+            ],
+            "description": "A plan discount already running on the subscription, which keeps lowering the monthly charges after this change. It never reduces charge_now_usd. Null when none applies to the next monthly charge, and once a change is no longer a quote."
+          },
           "effective_at": {
             "anyOf": [
               { "type": "string", "format": "date-time" },
@@ -13416,6 +14286,12 @@
           "purchase_cents": {
             "type": "integer",
             "enum": [500, 1000, 2500, 5000, 10000]
+          },
+          "approved_charge_usd": {
+            "type": "string",
+            "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+            "maxLength": 40,
+            "description": "Optional. The card charge the customer approved: the pack price less any promotion shown to them. When it differs from what would be charged, the purchase is refused with credit_purchase_price_changed and nothing is charged."
           }
         },
         "description": "Buy one credit pack now with the default card. The amount is the explicit approval of the charge."
@@ -13427,6 +14303,8 @@
           "id",
           "purchase_cents",
           "credit_usd",
+          "charged_usd",
+          "discount_usd",
           "status",
           "failure",
           "client_secret",
@@ -13447,6 +14325,18 @@
             "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
             "maxLength": 40
           },
+          "charged_usd": {
+            "type": "string",
+            "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+            "maxLength": 40,
+            "description": "What the card is charged: the pack price less any promotional discount. The pack's credit is unchanged."
+          },
+          "discount_usd": {
+            "type": "string",
+            "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+            "maxLength": 40,
+            "description": "The promotional discount taken off the pack price, or 0.000000."
+          },
           "status": {
             "type": "string",
             "enum": ["processing", "requires_action", "paid", "failed"]
@@ -14798,7 +15688,7 @@
       "CreateCustomerEndpointRequest": {
         "type": "object",
         "description": "Creates one project/environment endpoint. The service validates the final normalized destination and never returns it from health or diagnostic reads.",
-        "required": ["url", "event_types"],
+        "required": ["url"],
         "properties": {
           "url": {
             "type": "string",
@@ -14824,12 +15714,13 @@
       },
       "RotateCustomerEndpointRequest": {
         "type": "object",
-        "required": ["overlap_seconds"],
+        "required": [],
         "properties": {
           "overlap_seconds": {
             "type": "integer",
             "minimum": 60,
-            "maximum": 86400
+            "maximum": 86400,
+            "default": 86400
           }
         },
         "additionalProperties": false
@@ -15330,7 +16221,7 @@
       "CreateSubscriptionLinkRequest": {
         "type": "object",
         "description": "Creates one project- and environment-scoped, single-use authorization link.",
-        "required": ["subscriber_id", "channels"],
+        "required": ["subscriber_id"],
         "properties": {
           "subscriber_id": { "$ref": "#/components/schemas/OpaqueIdentifier" },
           "notifier_id": {
@@ -15346,7 +16237,7 @@
           },
           "connection_id": {
             "$ref": "#/components/schemas/OpaqueIdentifier",
-            "description": "The exact channel connection to authorize. Required for Slack. For Telegram or email, omission resolves an unambiguous default or sole compatible connection; it never selects an arbitrary fallback."
+            "description": "Optional exact connection. Otherwise the default or only compatible connection is used."
           },
           "address": {
             "$ref": "#/components/schemas/EmailAddress",
@@ -15381,16 +16272,6 @@
           {
             "if": { "properties": { "address": {} }, "required": ["address"] },
             "then": { "properties": { "channels": { "const": ["email"] } } }
-          },
-          {
-            "if": {
-              "properties": { "channels": { "const": ["slack"] } },
-              "required": ["channels"]
-            },
-            "then": {
-              "required": ["connection_id"],
-              "properties": { "connection_id": {} }
-            }
           }
         ],
         "additionalProperties": false
@@ -15509,9 +16390,14 @@
       "CreateMessageRequest": {
         "type": "object",
         "description": "Creates one logical message for one subscriber and one resolved channel binding.",
-        "required": ["to", "content"],
+        "required": ["to"],
         "properties": {
-          "to": { "$ref": "#/components/schemas/MessageTarget" },
+          "to": {
+            "oneOf": [
+              { "$ref": "#/components/schemas/MessageTarget" },
+              { "$ref": "#/components/schemas/OpaqueIdentifier" }
+            ]
+          },
           "notifier_id": {
             "allOf": [{ "$ref": "#/components/schemas/OpaqueIdentifier" }],
             "default": "default"
@@ -15524,10 +16410,10 @@
             "allOf": [{ "$ref": "#/components/schemas/OpaqueIdentifier" }],
             "description": "Optional channel connection to send through, from the environment's connections. The subscriber must be connected through it; the service never substitutes another connection or provider. A connection the subscriber has not connected through is refused as `subscriber_not_connected` when they are connected through another, and as an unchosen send would be (`subscriber_unbound` or `preferred_binding_unavailable`) when no connected channel can take the message. Omitted, the service chooses: the subscriber's preferred channel when they set one, otherwise the default connection when they are connected there, otherwise the connection they connected through most recently. The accepted message's `binding.connection_id` records the connection used. Implies `delivery_target: connection`."
           },
-          "content": { "$ref": "#/components/schemas/MessageContent" },
+          "content": { "$ref": "#/components/schemas/MessageContentInput" },
           "expires_at": {
             "$ref": "#/components/schemas/Timestamp",
-            "description": "Optional server-authoritative expiry no more than 24 hours after acceptance."
+            "description": "Optional server-authoritative expiry after acceptance, through year 9999. Omit for 24 hours."
           },
           "correlation_id": {
             "type": "string",
@@ -15553,6 +16439,28 @@
             "then": {
               "properties": { "delivery_target": { "const": "connection" } }
             }
+          },
+          {
+            "anyOf": [
+              {
+                "required": ["content"],
+                "properties": {
+                  "content": {
+                    "$ref": "#/components/schemas/MessageContentInput"
+                  }
+                },
+                "additionalProperties": true
+              },
+              {
+                "required": ["interaction"],
+                "properties": {
+                  "interaction": {
+                    "$ref": "#/components/schemas/InteractionSendRequest"
+                  }
+                },
+                "additionalProperties": true
+              }
+            ]
           }
         ],
         "additionalProperties": false
@@ -16086,7 +16994,9 @@
               "type": {
                 "const": "https://whooshbang.flowxo.com/problems/idempotency_key_required"
               },
-              "title": { "const": "Idempotency key required" },
+              "title": {
+                "enum": ["Invalid idempotency key", "Idempotency key required"]
+              },
               "status": { "const": 400 },
               "code": { "const": "idempotency_key_required" },
               "retryable": { "const": false }
@@ -16399,7 +17309,7 @@
         "additionalProperties": false
       },
       "InteractionSendRequest": {
-        "description": "Send-time interaction. Choose expires_in_seconds or expires_at; omit both for 24 hours from server acceptance. Idempotent replays retain the original resolved deadline.",
+        "description": "Options infer select; otherwise confirm. Typed replies require type: input. Omit expiry for 24 hours.",
         "oneOf": [
           { "$ref": "#/components/schemas/ConfirmInteractionSendRequest" },
           { "$ref": "#/components/schemas/SelectInteractionSendRequest" },
@@ -17682,9 +18592,6 @@
             "description": "Atomically create or resolve one subscriber and assert existing consent for an exact customer-owned email connection and domain. No verification message is sent. Revocation, suppression, recipient pause, holds and unhealthy authority take precedence. An omitted source is recorded as customer.",
             "required": [
               "subscriber_id",
-              "notifier_id",
-              "connection_id",
-              "domain_id",
               "address",
               "consented",
               "consented_at"
@@ -17694,7 +18601,8 @@
                 "$ref": "#/components/schemas/OpaqueIdentifier"
               },
               "notifier_id": {
-                "$ref": "#/components/schemas/OpaqueIdentifier"
+                "$ref": "#/components/schemas/OpaqueIdentifier",
+                "default": "default"
               },
               "connection_id": {
                 "$ref": "#/components/schemas/OpaqueIdentifier"
@@ -17721,9 +18629,6 @@
             "description": "Enroll an application-verified user for service email. This is relationship evidence, never consent or WhooshBang mailbox verification. An existing prior-consent binding with the same subscriber, address, notifier, connection and domain is reused with its original evidence and status.",
             "required": [
               "subscriber_id",
-              "notifier_id",
-              "connection_id",
-              "domain_id",
               "address",
               "basis",
               "source",
@@ -17734,7 +18639,8 @@
                 "$ref": "#/components/schemas/OpaqueIdentifier"
               },
               "notifier_id": {
-                "$ref": "#/components/schemas/OpaqueIdentifier"
+                "$ref": "#/components/schemas/OpaqueIdentifier",
+                "default": "default"
               },
               "connection_id": {
                 "$ref": "#/components/schemas/OpaqueIdentifier"
@@ -17776,7 +18682,7 @@
             "type": "array",
             "maxItems": 50,
             "uniqueItems": true,
-            "items": { "$ref": "#/components/schemas/DeveloperKey" }
+            "items": { "$ref": "#/components/schemas/GroupKey" }
           }
         },
         "additionalProperties": false
@@ -17848,7 +18754,7 @@
             "maxItems": 200,
             "uniqueItems": true,
             "description": "The keys of the static groups this subscriber belongs to in the environment asked about. Present when one subscriber is read.",
-            "items": { "$ref": "#/components/schemas/DeveloperKey" }
+            "items": { "$ref": "#/components/schemas/GroupKey" }
           },
           "last_activity_at": {
             "$ref": "#/components/schemas/Timestamp",
@@ -18030,9 +18936,9 @@
       "CreateSubscriberGroupRequest": {
         "type": "object",
         "description": "Creates one static, developer-managed subscriber group.",
-        "required": ["key", "display_name"],
+        "required": ["key"],
         "properties": {
-          "key": { "$ref": "#/components/schemas/DeveloperKey" },
+          "key": { "$ref": "#/components/schemas/GroupKey" },
           "display_name": {
             "type": "string",
             "minLength": 1,
@@ -18045,8 +18951,8 @@
       "UpdateSubscriberGroupRequest": {
         "type": "object",
         "description": "Renames or redescribes an active group. Its key and static membership model cannot change.",
-        "required": ["row_version"],
-        "minProperties": 2,
+        "required": [],
+        "minProperties": 1,
         "properties": {
           "row_version": { "type": "integer", "minimum": 1 },
           "display_name": {
@@ -18056,7 +18962,14 @@
           },
           "description": { "type": ["string", "null"], "maxLength": 500 }
         },
-        "additionalProperties": false
+        "additionalProperties": false,
+        "anyOf": [
+          {
+            "required": ["display_name"],
+            "properties": { "display_name": {} }
+          },
+          { "required": ["description"], "properties": { "description": {} } }
+        ]
       },
       "SubscriberGroup": {
         "type": "object",
@@ -18083,7 +18996,7 @@
           "id": { "$ref": "#/components/schemas/OpaqueIdentifier" },
           "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" },
           "environment": { "$ref": "#/components/schemas/Environment" },
-          "key": { "$ref": "#/components/schemas/DeveloperKey" },
+          "key": { "$ref": "#/components/schemas/GroupKey" },
           "display_name": {
             "type": "string",
             "minLength": 1,
@@ -18150,7 +19063,7 @@
         ],
         "properties": {
           "group_id": { "$ref": "#/components/schemas/OpaqueIdentifier" },
-          "group_key": { "$ref": "#/components/schemas/DeveloperKey" },
+          "group_key": { "$ref": "#/components/schemas/GroupKey" },
           "subscriber_id": { "$ref": "#/components/schemas/OpaqueIdentifier" },
           "subscriber_name": {
             "type": "string",
@@ -18191,7 +19104,7 @@
         "type": "object",
         "required": ["group_key", "membership_revision", "items"],
         "properties": {
-          "group_key": { "$ref": "#/components/schemas/DeveloperKey" },
+          "group_key": { "$ref": "#/components/schemas/GroupKey" },
           "membership_revision": { "type": "integer", "minimum": 0 },
           "items": {
             "type": "array",
@@ -18215,14 +19128,17 @@
       "CreateGroupBroadcastRequest": {
         "type": "object",
         "description": "Creates one group broadcast using the existing ordinary message envelope. The group target comes only from the path.",
-        "required": ["content"],
+        "required": [],
         "properties": {
           "notifier_id": {
             "allOf": [{ "$ref": "#/components/schemas/OpaqueIdentifier" }],
             "default": "default"
           },
-          "content": { "$ref": "#/components/schemas/MessageContent" },
-          "expires_at": { "$ref": "#/components/schemas/Timestamp" },
+          "content": { "$ref": "#/components/schemas/MessageContentInput" },
+          "expires_at": {
+            "$ref": "#/components/schemas/Timestamp",
+            "description": "Optional server-authoritative expiry after acceptance, through year 9999. Omit for 24 hours."
+          },
           "correlation_id": {
             "type": "string",
             "minLength": 1,
@@ -18238,7 +19154,31 @@
             "description": "Omitted means service. Marketing refuses service-only bindings before charging and at every delayed dispatch."
           }
         },
-        "additionalProperties": false
+        "additionalProperties": false,
+        "allOf": [
+          {
+            "anyOf": [
+              {
+                "required": ["content"],
+                "properties": {
+                  "content": {
+                    "$ref": "#/components/schemas/MessageContentInput"
+                  }
+                },
+                "additionalProperties": true
+              },
+              {
+                "required": ["interaction"],
+                "properties": {
+                  "interaction": {
+                    "$ref": "#/components/schemas/InteractionSendRequest"
+                  }
+                },
+                "additionalProperties": true
+              }
+            ]
+          }
+        ]
       },
       "GroupBroadcast": {
         "type": "object",
@@ -18266,7 +19206,7 @@
           "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" },
           "environment": { "$ref": "#/components/schemas/Environment" },
           "group_id": { "$ref": "#/components/schemas/OpaqueIdentifier" },
-          "group_key": { "$ref": "#/components/schemas/DeveloperKey" },
+          "group_key": { "$ref": "#/components/schemas/GroupKey" },
           "audience_revision": { "type": "integer", "minimum": 0 },
           "status": {
             "type": "string",
@@ -18522,6 +19462,61 @@
         },
         "additionalProperties": false
       },
+      "NotificationImageInput": {
+        "type": "object",
+        "description": "One optional provider-neutral illustrative image. The notification content remains complete without the pixels.",
+        "required": ["asset_id"],
+        "properties": {
+          "asset_id": {
+            "$ref": "#/components/schemas/NotificationImageAssetId"
+          },
+          "purpose": { "const": "illustration", "default": "illustration" },
+          "description": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000,
+            "pattern": "^(?=.*\\S)[^\\u0000-\\u001F\\u007F]+$",
+            "x-max-utf8-bytes": 4000,
+            "description": "Optional accessible description preserved by every adapter. Omit it for a decorative illustration; notification text must remain complete without the image."
+          }
+        },
+        "additionalProperties": false
+      },
+      "TextContentInput": {
+        "type": "object",
+        "required": ["text"],
+        "properties": {
+          "type": { "const": "text" },
+          "format": {
+            "type": "string",
+            "enum": ["plain", "markdown"],
+            "description": "Text format. Omitted means plain text. Markdown supports headings, paragraphs, emphasis, strong emphasis, code, lists, quotes and safe HTTP(S) links; raw HTML and remote images are never executed or fetched."
+          },
+          "text": {
+            "description": "The complete notification content. This remains authoritative and sufficient when an adapter cannot render optional structure.",
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 8192,
+            "x-max-utf8-bytes": 8192
+          },
+          "title": {
+            "description": "An optional semantic title. The adapter chooses its native presentation.",
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200,
+            "x-max-utf8-bytes": 800
+          },
+          "sections": {
+            "description": "Optional ordered semantic sections that enhance, but never replace, the complete text.",
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 12,
+            "items": { "$ref": "#/components/schemas/StructuredTextSection" }
+          },
+          "image": { "$ref": "#/components/schemas/NotificationImageInput" }
+        },
+        "additionalProperties": false
+      },
       "DocumentSectionBlock": {
         "description": "One prose section in an ordered portable document.",
         "type": "object",
@@ -18655,10 +19650,10 @@
           { "$ref": "#/components/schemas/DocumentDetailsBlock" }
         ]
       },
-      "DocumentContent": {
+      "DocumentContentInput": {
         "description": "An authoritative ordered portable notification document that every delivery adapter renders faithfully.",
         "type": "object",
-        "required": ["type", "blocks"],
+        "required": ["blocks"],
         "properties": {
           "type": { "const": "document" },
           "title": {
@@ -18675,34 +19670,22 @@
             "maxItems": 24,
             "items": { "$ref": "#/components/schemas/DocumentBlock" }
           },
-          "image": { "$ref": "#/components/schemas/NotificationImage" }
+          "image": { "$ref": "#/components/schemas/NotificationImageInput" }
         },
         "additionalProperties": false
       },
-      "MessageContent": {
-        "oneOf": [
-          { "$ref": "#/components/schemas/TextContent" },
-          { "$ref": "#/components/schemas/DocumentContent" }
-        ]
-      },
-      "MetadataValue": {
+      "MessageContentInput": {
         "oneOf": [
-          { "type": "string" },
-          { "type": "number" },
-          { "type": "boolean" },
-          { "type": "null" }
+          {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 8192,
+            "x-max-utf8-bytes": 8192
+          },
+          { "$ref": "#/components/schemas/TextContentInput" },
+          { "$ref": "#/components/schemas/DocumentContentInput" }
         ]
       },
-      "Metadata": {
-        "type": "object",
-        "description": "Bounded customer correlation data. Do not include secrets or personal data.",
-        "maxProperties": 20,
-        "propertyNames": { "minLength": 1, "maxLength": 64 },
-        "additionalProperties": {
-          "$ref": "#/components/schemas/MetadataValue"
-        },
-        "x-max-json-bytes": 4096
-      },
       "InteractionPrompt": {
         "type": "string",
         "minLength": 1,
@@ -18715,14 +19698,14 @@
       },
       "InteractionCorrelationId": {
         "type": "string",
-        "minLength": 8,
+        "minLength": 1,
         "maxLength": 128,
         "pattern": "^[^\\u0000-\\u001F\\u007F]+$",
         "description": "Caller-owned opaque correlation returned as data, never treated as execution authority."
       },
       "ConfirmInteractionSendRequest": {
         "type": "object",
-        "required": ["type", "prompt"],
+        "required": ["prompt"],
         "properties": {
           "type": { "const": "confirm" },
           "prompt": { "$ref": "#/components/schemas/InteractionPrompt" },
@@ -18751,30 +19734,55 @@
           "properties": { "expires_at": {}, "expires_in_seconds": {} }
         }
       },
-      "InteractionOption": {
-        "type": "object",
-        "required": ["value", "label"],
-        "properties": {
-          "value": {
+      "InteractionOptionInput": {
+        "oneOf": [
+          {
             "type": "string",
             "minLength": 1,
-            "maxLength": 128,
-            "pattern": "^[^\\u0000-\\u001F\\u007F]+$",
-            "description": "Opaque customer data. It is never interpreted as a command."
+            "maxLength": 120,
+            "pattern": "^[^\\u0000-\\u001F\\u007F]+$"
           },
-          "label": { "type": "string", "minLength": 1, "maxLength": 120 },
-          "intent": {
-            "type": "string",
-            "enum": ["accept", "destructive", "informational", "neutral"],
-            "default": "neutral",
-            "description": "What choosing this option does, so a channel can present it accordingly. Describes consequence rather than appearance: a channel renders `accept` green where it can, `destructive` red, `informational` prominent, and `neutral` plainly. A channel that cannot colour a control ignores this and the option still renders. Omitted means `neutral`."
+          {
+            "type": "object",
+            "required": ["label"],
+            "properties": {
+              "value": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128,
+                "pattern": "^[^\\u0000-\\u001F\\u007F]+$",
+                "description": "Defaults to label. Opaque customer data, never a command."
+              },
+              "label": { "type": "string", "minLength": 1, "maxLength": 120 },
+              "intent": {
+                "type": "string",
+                "enum": ["accept", "destructive", "informational", "neutral"],
+                "default": "neutral",
+                "description": "What choosing this option does, so a channel can present it accordingly. Describes consequence rather than appearance: a channel renders `accept` green where it can, `destructive` red, `informational` prominent, and `neutral` plainly. A channel that cannot colour a control ignores this and the option still renders. Omitted means `neutral`."
+              }
+            },
+            "additionalProperties": false,
+            "allOf": [
+              {
+                "if": { "properties": { "value": {} }, "required": ["value"] },
+                "else": {
+                  "properties": {
+                    "label": {
+                      "pattern": "^[^\\u0000-\\u001F\\u007F]+$",
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            ],
+            "$comment": "The conditional constraint applies only when the label is used as the value. Keep the TypeScript input shape explicit because the generator omits object properties for conditional schemas.",
+            "x-typescript-type": "{ label: string; value?: string; intent?: \"accept\" | \"destructive\" | \"informational\" | \"neutral\" }"
           }
-        },
-        "additionalProperties": false
+        ]
       },
       "SelectInteractionSendRequest": {
         "type": "object",
-        "required": ["type", "prompt", "options"],
+        "required": ["prompt", "options"],
         "properties": {
           "type": { "const": "select" },
           "prompt": { "$ref": "#/components/schemas/InteractionPrompt" },
@@ -18782,7 +19790,7 @@
             "type": "array",
             "minItems": 2,
             "maxItems": 6,
-            "items": { "$ref": "#/components/schemas/InteractionOption" },
+            "items": { "$ref": "#/components/schemas/InteractionOptionInput" },
             "x-unique-property": "value"
           },
           "expires_at": {
@@ -18829,6 +19837,24 @@
           "properties": { "expires_at": {}, "expires_in_seconds": {} }
         }
       },
+      "MetadataValue": {
+        "oneOf": [
+          { "type": "string" },
+          { "type": "number" },
+          { "type": "boolean" },
+          { "type": "null" }
+        ]
+      },
+      "Metadata": {
+        "type": "object",
+        "description": "Bounded customer correlation data. Do not include secrets or personal data.",
+        "maxProperties": 20,
+        "propertyNames": { "minLength": 1, "maxLength": 64 },
+        "additionalProperties": {
+          "$ref": "#/components/schemas/MetadataValue"
+        },
+        "x-max-json-bytes": 4096
+      },
       "HighestProvenProviderState": {
         "type": "string",
         "enum": ["none", "provider_accepted"],
@@ -18892,12 +19918,12 @@
         "type": "string",
         "enum": ["open", "answered", "expired", "cancelled", "retired"]
       },
-      "DeveloperKey": {
+      "GroupKey": {
         "type": "string",
         "minLength": 1,
         "maxLength": 63,
-        "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
-        "description": "A stable, lowercase developer key used by registered return destinations and subscriber groups."
+        "pattern": "^[A-Za-z0-9]+(?:[-_][A-Za-z0-9]+)*$",
+        "description": "A stable, case-sensitive subscriber group key. Existing keys are preserved exactly."
       },
       "BroadcastAggregate": {
         "type": "object",
@@ -20231,6 +21257,36 @@
           }
         ]
       },
+      "DocumentContent": {
+        "description": "An authoritative ordered portable notification document that every delivery adapter renders faithfully.",
+        "type": "object",
+        "required": ["type", "blocks"],
+        "properties": {
+          "type": { "const": "document" },
+          "title": {
+            "description": "An optional semantic document title. The adapter chooses its native presentation.",
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200,
+            "x-max-utf8-bytes": 800
+          },
+          "blocks": {
+            "description": "The complete portable document in exact authored order.",
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 24,
+            "items": { "$ref": "#/components/schemas/DocumentBlock" }
+          },
+          "image": { "$ref": "#/components/schemas/NotificationImage" }
+        },
+        "additionalProperties": false
+      },
+      "MessageContent": {
+        "oneOf": [
+          { "$ref": "#/components/schemas/TextContent" },
+          { "$ref": "#/components/schemas/DocumentContent" }
+        ]
+      },
       "RecipientBrand": {
         "type": "object",
         "description": "Constrained recipient-facing brand tokens. Arbitrary markup, CSS, scripts, remote assets, fonts, and tracking inputs are structurally absent.",
@@ -20261,6 +21317,13 @@
         "pattern": "^https?://[^/?#*\\s]+(?::[0-9]{1,5})?/?$",
         "description": "One exact scheme, host, and optional port, in any spelling that means that same origin. A trailing slash, an uppercase host, and an explicitly written default port are accepted and stored in canonical form. Paths, queries, fragments, credentials, and wildcards are forbidden; HTTP is accepted only for localhost or synthetic .test configuration."
       },
+      "DeveloperKey": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 63,
+        "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+        "description": "A stable, lowercase developer key used by registered return destinations and subscriber groups."
+      },
       "RegisteredReturnUrl": {
         "type": "string",
         "format": "uri",
@@ -20416,7 +21479,7 @@
       "provider-capabilities-v1.schema": {
         "$schema": "https://json-schema.org/draft/2020-12/schema",
         "$id": "https://whooshbang.flowxo.com/schemas/provider-capabilities-v1.schema.json",
-        "x-contract-version": "2.4.0",
+        "x-contract-version": "2.6.0",
         "title": "ProviderCapabilitiesV1",
         "description": "Provider-neutral, renderer-facing delivery and interaction capabilities with explicit degradation.",
         "type": "object",
@@ -20625,7 +21688,7 @@
         "description": "How many of a day's messages fall in one group. `key` is a `MessageState` when grouping by state, a `Channel` when grouping by channel, and a channel connection id when grouping by connection. Groups with no messages are omitted, and a list holds at most the 200 largest groups, largest first.",
         "required": ["key", "count"],
         "properties": {
-          "key": { "type": "string", "minLength": 1, "maxLength": 128 },
+          "key": { "$ref": "#/components/schemas/GroupKey" },
           "count": { "type": "integer", "minimum": 1 }
         },
         "additionalProperties": false
@@ -20699,6 +21762,27 @@
         },
         "additionalProperties": false
       },
+      "InteractionOption": {
+        "type": "object",
+        "required": ["value", "label"],
+        "properties": {
+          "value": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "pattern": "^[^\\u0000-\\u001F\\u007F]+$",
+            "description": "Opaque customer data. It is never interpreted as a command."
+          },
+          "label": { "type": "string", "minLength": 1, "maxLength": 120 },
+          "intent": {
+            "type": "string",
+            "enum": ["accept", "destructive", "informational", "neutral"],
+            "default": "neutral",
+            "description": "What choosing this option does, so a channel can present it accordingly. Describes consequence rather than appearance: a channel renders `accept` green where it can, `destructive` red, `informational` prominent, and `neutral` plainly. A channel that cannot colour a control ignores this and the option still renders. Omitted means `neutral`."
+          }
+        },
+        "additionalProperties": false
+      },
       "SelectInteractionRequest": {
         "type": "object",
         "required": ["type", "prompt", "options", "expires_at"],
@@ -20783,9 +21867,9 @@
               "idempotencyKeyRequired": {
                 "value": {
                   "type": "https://whooshbang.flowxo.com/problems/idempotency_key_required",
-                  "title": "Idempotency key required",
+                  "title": "Invalid idempotency key",
                   "status": 400,
-                  "detail": "Provide an Idempotency-Key containing 8 to 255 visible ASCII characters.",
+                  "detail": "Idempotency-Key must be 8 to 255 visible ASCII characters.",
                   "code": "idempotency_key_required",
                   "diagnostic_id": "diag_idem_required_001",
                   "retryable": false
@@ -21197,5 +22281,5 @@
       }
     }
   },
-  "x-contract-version": "2.4.0"
+  "x-contract-version": "2.6.0"
 }