{ "openapi": "3.1.1", "info": { "title": "WhooshBang API", "version": "1.0.0-rc.25", "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": { "name": "WhooshBang Support", "url": "https://flowxo.com/contact" }, "license": { "name": "Proprietary", "url": "https://flowxo.com/terms" } }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "servers": [ { "url": "https://api.whooshbang.com", "description": "Environment is selected by the bearer credential, not the URL or body." } ], "security": [{ "bearerCredential": [] }], "tags": [ { "name": "Organization", "description": "The current Clerk organization projected as a WhooshBang organization." }, { "name": "Projects", "description": "Organization-scoped applications with transactionally bootstrapped test/live environments." }, { "name": "API credentials", "description": "Human-administered, environment-scoped bearer credentials with one-time secret reveal." }, { "name": "Organization credentials", "description": "Human-administered, organization-scoped bearer credentials that name their project and environment per call." }, { "name": "Provider installations", "description": "Organization-owned provider authority established through credential-free browser handoffs." }, { "name": "Subscription links", "description": "Single-use, expiring Telegram authorization links." }, { "name": "Messages", "description": "Asynchronous logical messages and their highest proven outcomes." }, { "name": "Machine clients", "description": "Project-administered, destination-bound local-client identities and one-way credential metadata." }, { "name": "Machine events", "description": "Durable per-machine long polling and contiguous acknowledgement." }, { "name": "Capabilities", "description": "Provider-neutral rendering and evidence capabilities." }, { "name": "Customer endpoints", "description": "Verified signed-event destinations with one-time secret lifecycle and content-free diagnostics." }, { "name": "Channel connections", "description": "One environment's selection of a provider identity, with credential custody held internally and never exposed." }, { "name": "Recipient experience", "description": "Constrained project brand, exact environment browser policy, and attenuated recipient sessions." }, { "name": "Subscribers", "description": "Application-owned subscriber identity and transactional initial static-group membership." }, { "name": "Recipient groups", "description": "Environment-scoped static groups and monotonic membership generations." }, { "name": "Group broadcasts", "description": "Durable group acceptance and aggregate projection over ordinary child messages." } ], "paths": { "/v1/organization": { "get": { "operationId": "getOrganization", "summary": "Read the current organization projection", "description": "Returns the WhooshBang organization selected by the verified Clerk\norganization session and the caller's projected role. Clerk organization\nand user identifiers are never public response fields.\n", "tags": ["Organization"], "security": [{ "clerkSession": [] }, { "bearerGrant": [] }], "x-organization-membership": "required", "responses": { "200": { "description": "The current organization projection.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationProjection" }, "examples": { "projectedOrganization": { "value": { "id": "organization_synthetic_001", "name": "Synthetic Organization", "status": "active", "membership": { "role": "admin" }, "created_at": "2026-07-28T12:00:00Z", "updated_at": "2026-07-28T12:00:00Z", "diagnostic_id": "diag_organization_synthetic_001" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/organization/close": { "post": { "operationId": "closeOrganization", "summary": "Close the current customer organization", "description": "Terminally closes the organization selected by the verified Clerk\norganization session. Only an administrator may close it. OAuth grants\nand API credentials are deliberately excluded: delegated authority must\nnot be able to erase the organization that granted it.\n\nThe request requires the exact confirmation `close-organization`. Repeating a\ncompleted closure is safe and returns the original `closed_at`. The\nresult names provider-owned resources the administrator must still retire\noutside WhooshBang, such as revoking a customer-managed Telegram bot token\nin BotFather; no provider credential is returned.\n", "tags": ["Organization"], "security": [{ "clerkSession": [] }], "x-organization-membership": "required", "x-required-membership-role": "admin", "x-repeat-semantics": { "same_target": "idempotent", "secret_returned": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloseOrganizationRequest" } } } }, "responses": { "200": { "description": "The organization is closed, with any manual provider retirement still required.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationClosureResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/provider-installations": { "get": { "operationId": "listProviderInstallations", "summary": "List customer-owned email provider installations", "description": "Returns only safe WhooshBang lifecycle, health, deployment authorization availability and resumable authorization progress for the current organization. Provider team identity, grants and credentials are absent.", "tags": ["Provider installations"], "security": [ { "clerkSession": [] }, { "bearerGrant": ["connections:read"] } ], "x-required-scopes": ["connections:read"], "x-organization-membership": "required", "parameters": [ { "$ref": "#/components/parameters/ListAfterCursor" }, { "$ref": "#/components/parameters/ListPageLimit" }, { "$ref": "#/components/parameters/PageNumber" } ], "responses": { "200": { "description": "The current organization's email provider installations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInstallationCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "createProviderInstallation", "summary": "Connect a customer-owned Resend team", "description": "Starts one short-lived OAuth authorization for an organization administrator. The returned installation contains the first-party browser handoff and no provider credential.", "tags": ["Provider installations"], "security": [ { "clerkSession": [] }, { "bearerGrant": ["connections:write"] } ], "x-required-scopes": ["connections:write"], "x-organization-membership": "required", "x-required-membership-role": "admin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProviderInstallationRequest" } } } }, "responses": { "201": { "description": "The pending installation and resumable authorization handoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInstallation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/provider-installations/{provider_installation_id}": { "parameters": [ { "name": "provider_installation_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } } ], "get": { "operationId": "getProviderInstallation", "summary": "Read one customer-owned email provider installation", "tags": ["Provider installations"], "security": [ { "clerkSession": [] }, { "bearerGrant": ["connections:read"] } ], "x-required-scopes": ["connections:read"], "x-organization-membership": "required", "responses": { "200": { "description": "Safe installation lifecycle and authorization progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInstallation" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "disconnectProviderInstallation", "summary": "Disconnect a customer-owned email provider installation", "description": "Removes local authority first, deletes only WhooshBang's owned webhook while authorization remains, revokes the newest refresh authority, retires dependent edges, and then destroys credential custody.", "tags": ["Provider installations"], "security": [ { "clerkSession": [] }, { "bearerGrant": ["connections:write"] } ], "x-required-scopes": ["connections:write"], "x-organization-membership": "required", "x-required-membership-role": "admin", "responses": { "204": { "description": "The installation is disconnected or was already absent." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/provider-installations/{provider_installation_id}/reconnect": { "post": { "operationId": "reconnectProviderInstallation", "summary": "Reauthorize one customer-owned email provider installation", "description": "Starts a new short-lived OAuth handoff. Completion succeeds only when the signature-verified access token identifies the same Resend team as the existing installation.", "tags": ["Provider installations"], "security": [ { "clerkSession": [] }, { "bearerGrant": ["connections:write"] } ], "x-required-scopes": ["connections:write"], "x-organization-membership": "required", "x-required-membership-role": "admin", "parameters": [ { "name": "provider_installation_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } } ], "responses": { "201": { "description": "The installation with a resumable reauthorization handoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInstallation" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/email-domains": { "get": { "operationId": "listEmailDomains", "summary": "List account-owned email domains", "description": "Returns one page of the resumable lifecycle, separate sending and receiving readiness, exact DNS records, safe failures, and exact connection assignments for domains in the current organization.", "tags": ["Email domains"], "security": [ { "clerkSession": [] }, { "bearerGrant": ["connections:read"] } ], "x-required-scopes": ["connections:read"], "x-organization-membership": "required", "parameters": [ { "$ref": "#/components/parameters/ListAfterCursor" }, { "$ref": "#/components/parameters/ListPageLimit" }, { "$ref": "#/components/parameters/PageNumber" } ], "responses": { "200": { "description": "The organization's customer-owned email domains.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDomainCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "createEmailDomain", "summary": "Create or safely adopt a dedicated sending subdomain", "description": "Canonicalizes the IDNA domain, reconciles the connected team before creating, enables sending and receiving with tracking off, and begins the durable guided-DNS lifecycle. Repeating the same organization, installation and domain returns the existing lifecycle.", "tags": ["Email domains"], "security": [ { "clerkSession": [] }, { "bearerGrant": ["connections:write"] } ], "x-required-scopes": ["connections:write"], "x-organization-membership": "required", "x-required-membership-role": "admin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmailDomainRequest" } } } }, "responses": { "201": { "description": "The new resumable domain lifecycle.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDomain" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/email-domains/{email_domain_id}": { "parameters": [ { "name": "email_domain_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } } ], "get": { "operationId": "getEmailDomain", "summary": "Read one resumable email-domain checklist", "tags": ["Email domains"], "security": [ { "clerkSession": [] }, { "bearerGrant": ["connections:read"] } ], "x-required-scopes": ["connections:read"], "x-organization-membership": "required", "responses": { "200": { "description": "Current domain, DNS, capability and assignment state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDomain" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteEmailDomain", "summary": "Remove an unassigned customer email domain", "description": "Revokes DNS-administrator links immediately and queues deletion of the exact provider domain. Active connection assignments must be removed first. A completed deletion can be created again later.", "tags": ["Email domains"], "security": [ { "clerkSession": [] }, { "bearerGrant": ["connections:write"] } ], "x-required-scopes": ["connections:write"], "x-organization-membership": "required", "x-required-membership-role": "admin", "responses": { "202": { "description": "Provider deletion is queued or already complete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDomain" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/email-domains/{email_domain_id}/verify": { "post": { "operationId": "verifyEmailDomain", "summary": "Confirm that DNS is ready for verification", "description": "Requests a distinct destructive provider verification attempt. After the first attempt, a request is admitted only after ten minutes and only when no DNS-record status has moved since the prior trigger; otherwise it safely returns the unchanged lifecycle.", "tags": ["Email domains"], "security": [ { "clerkSession": [] }, { "bearerGrant": ["connections:write"] } ], "x-required-scopes": ["connections:write"], "x-organization-membership": "required", "x-required-membership-role": "admin", "parameters": [ { "name": "email_domain_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } } ], "responses": { "200": { "description": "The current lifecycle; repeated early requests do not reset provider verification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDomain" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/email-domains/{email_domain_id}/retry": { "post": { "operationId": "retryEmailDomain", "summary": "Resume a provider-action-required domain", "description": "Reconciles by canonical name when creation has no provider reference, resumes deletion when cleanup was interrupted, or starts a fresh bounded roundtrip generation after the customer resolves the provider-side condition.", "tags": ["Email domains"], "security": [ { "clerkSession": [] }, { "bearerGrant": ["connections:write"] } ], "x-required-scopes": ["connections:write"], "x-organization-membership": "required", "x-required-membership-role": "admin", "parameters": [ { "name": "email_domain_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } } ], "responses": { "200": { "description": "Current domain after the corrective workflow is resumed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDomain" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/email-domains/{email_domain_id}/guide-link": { "parameters": [ { "name": "email_domain_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } } ], "post": { "operationId": "createEmailDomainGuideLink", "summary": "Create a short-lived secret-free DNS administrator link", "description": "Revokes the prior link and returns the domain with a new 24-hour instruction URL. The page contains only the domain, exact DNS records, statuses, and reviewed manual guidance.", "tags": ["Email domains"], "security": [ { "clerkSession": [] }, { "bearerGrant": ["connections:write"] } ], "x-required-scopes": ["connections:write"], "x-organization-membership": "required", "x-required-membership-role": "admin", "responses": { "201": { "description": "The domain carrying the one-time visible instruction URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDomain" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "revokeEmailDomainGuideLink", "summary": "Revoke every live DNS administrator link for a domain", "tags": ["Email domains"], "security": [ { "clerkSession": [] }, { "bearerGrant": ["connections:write"] } ], "x-required-scopes": ["connections:write"], "x-organization-membership": "required", "x-required-membership-role": "admin", "responses": { "204": { "description": "Live links are revoked, or none existed." }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/email-domain-guides/{token}": { "get": { "operationId": "readEmailDomainGuide", "summary": "Read a short-lived secret-free DNS guide", "description": "Public bearer link for a DNS administrator. It carries no WhooshBang session, OAuth grant, provider identifier, or credential and is unavailable after expiry or revocation.", "tags": ["Email domains"], "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "responses": { "200": { "description": "A complete manual DNS checklist.", "content": { "text/html": { "schema": { "type": "string" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/organization/credentials": { "get": { "operationId": "listOrganizationCredentials", "summary": "List safe organization credential metadata", "description": "Returns only credentials owned by the organization selected by the verified\nClerk organization session. Secrets and digest material are never\nreturned.\n", "tags": ["Organization credentials"], "security": [{ "clerkSession": [] }], "x-organization-membership": "required", "parameters": [ { "$ref": "#/components/parameters/ApiCredentialAfterCursor" }, { "$ref": "#/components/parameters/ApiCredentialPageLimit" }, { "$ref": "#/components/parameters/PageNumber" } ], "responses": { "200": { "description": "A stable page of safe organization credential metadata.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationCredentialCollection" }, "examples": { "organizationCredentials": { "value": { "items": [ { "id": "ocred_AAAAAAAAAAAAAAAAAAAAAA", "prefix": "wb_oc1.ocred_AAAAAAAA", "label": "Synthetic release automation", "scopes": [ "organization:read", "messages:write", "messages:read" ], "created_by": "member_synthetic_001", "created_at": "2026-07-25T17:45:00Z", "last_used_at": "2026-07-25T17:50:00Z", "status": "active" } ], "page": 1, "page_size": 50, "total": 1 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createOrganizationCredential", "summary": "Create an organization-scoped API credential", "description": "Creates one credential against the whole organization. It names no project\nand no environment: a request names them in its path, and the\ncredential's authority on that path is the intersection of its scopes\nwith the project-credential vocabulary, so it is never wider than a\nproject credential would have been for the same project environment.\nThe complete bearer secret appears only in this creation response. It\ncannot be read later and is never replayed from an idempotency cache.\n", "tags": ["Organization credentials"], "security": [{ "clerkSession": [] }], "x-organization-membership": "required", "x-secret-reveal": { "responses": 1, "replayable": false, "later_reads": "metadata_only" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationCredentialRequest" }, "examples": { "createOrganizationCredential": { "value": { "label": "Release automation", "scopes": [ "organization:read", "messages:write", "messages:read" ] } } } } } }, "responses": { "201": { "description": "Creation-only secret reveal and safe credential metadata.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationCredentialSecretReveal" }, "examples": { "createdOrganizationCredential": { "value": { "credential": { "id": "ocred_AAAAAAAAAAAAAAAAAAAAAA", "prefix": "wb_oc1.ocred_AAAAAAAA", "label": "Synthetic release automation", "scopes": [ "organization:read", "messages:write", "messages:read" ], "created_by": "member_synthetic_001", "created_at": "2026-07-25T17:45:00Z", "status": "active" }, "secret": "wb_oc1.ocred_AAAAAAAAAAAAAAAAAAAAAA.AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/organization/credentials/{organization_credential_id}/rotate": { "parameters": [ { "$ref": "#/components/parameters/OrganizationCredentialId" } ], "post": { "operationId": "rotateOrganizationCredential", "summary": "Rotate an organization-scoped API credential", "description": "Creates one replacement with the same label and scopes. The complete new\nbearer secret appears only in this response. The replaced credential\nremains active for the explicitly declared overlap, from zero through\n86400 seconds, then becomes terminally revoked. A revoked credential\ncannot be rotated. Missing and out-of-organization credentials use the same\nnon-enumerating `404`.\n", "tags": ["Organization credentials"], "security": [{ "clerkSession": [] }], "x-organization-membership": "required", "x-secret-reveal": { "responses": 1, "replayable": false, "later_reads": "metadata_only" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateOrganizationCredentialRequest" }, "examples": { "rotateOrganizationCredential": { "value": { "overlap_seconds": 3600 } } } } } }, "responses": { "201": { "description": "Creation-only replacement secret and safe metadata for both credentials.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationCredentialRotation" }, "examples": { "rotatedOrganizationCredential": { "value": { "credential": { "credential": { "id": "ocred_BBBBBBBBBBBBBBBBBBBBBA", "prefix": "wb_oc1.ocred_BBBBBBBB", "label": "Synthetic release automation", "scopes": [ "organization:read", "messages:write", "messages:read" ], "created_by": "member_synthetic_001", "created_at": "2026-07-25T17:45:00Z", "status": "active" }, "secret": "wb_oc1.ocred_BBBBBBBBBBBBBBBBBBBBBA.BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBA" }, "replaced_credential": { "id": "ocred_AAAAAAAAAAAAAAAAAAAAAA", "prefix": "wb_oc1.ocred_AAAAAAAA", "label": "Synthetic release automation", "scopes": [ "organization:read", "messages:write", "messages:read" ], "created_by": "member_synthetic_001", "created_at": "2026-07-25T17:45:00Z", "last_used_at": "2026-07-25T17:50:00Z", "scheduled_revocation_at": "2026-07-25T18:45:00Z", "status": "active" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/organization/credentials/{organization_credential_id}/revoke": { "parameters": [ { "$ref": "#/components/parameters/OrganizationCredentialId" } ], "post": { "operationId": "revokeOrganizationCredential", "summary": "Revoke an organization-scoped API credential", "description": "Immediately and terminally revokes the selected credential. Repeating\nthe request for the same visible credential is safe and returns the\nsame revoked metadata without revealing secret or digest material.\nMissing and out-of-organization credentials use the same non-enumerating\n`404`.\n", "tags": ["Organization credentials"], "security": [{ "clerkSession": [] }], "x-organization-membership": "required", "x-repeat-semantics": { "same_target": "idempotent", "secret_returned": false }, "responses": { "200": { "description": "Safe terminal credential metadata.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationCredential" }, "examples": { "revokedOrganizationCredential": { "value": { "id": "ocred_AAAAAAAAAAAAAAAAAAAAAA", "prefix": "wb_oc1.ocred_AAAAAAAA", "label": "Synthetic release automation", "scopes": [ "organization:read", "messages:write", "messages:read" ], "created_by": "member_synthetic_001", "created_at": "2026-07-25T17:45:00Z", "last_used_at": "2026-07-25T17:50:00Z", "status": "revoked", "revoked_at": "2026-07-25T17:55:00Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/projects": { "get": { "operationId": "listProjects", "summary": "List projects in the current organization", "description": "Returns only projects owned by the organization selected by the verified\nClerk organization session. Every project includes its complete test/live\nenvironment and default-notifier bootstrap.\n", "tags": ["Projects"], "security": [ { "clerkSession": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["projects:read"], "x-organization-membership": "required", "parameters": [ { "$ref": "#/components/parameters/ProjectAfterCursor" }, { "$ref": "#/components/parameters/ProjectPageLimit" }, { "$ref": "#/components/parameters/PageNumber" } ], "responses": { "200": { "description": "A stable page of projects in the current organization.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCollection" }, "examples": { "projects": { "value": { "items": [ { "id": "project_synthetic_001", "organization_id": "organization_synthetic_001", "name": "Synthetic Alerts", "slug": "synthetic-alerts", "status": "active", "default_locale": "es", "environments": [ { "id": "environment_synthetic_test_001", "project_id": "project_synthetic_001", "kind": "test", "status": "active", "default_notifier": { "id": "notifier_synthetic_test_default_001", "environment_id": "environment_synthetic_test_001", "display_name": "Default", "status": "active", "is_default": true } }, { "id": "environment_synthetic_live_001", "project_id": "project_synthetic_001", "kind": "live", "status": "active", "default_notifier": { "id": "notifier_synthetic_live_default_001", "environment_id": "environment_synthetic_live_001", "display_name": "Default", "status": "active", "is_default": true } } ], "created_at": "2026-07-28T12:05:00Z", "updated_at": "2026-07-28T12:05:00Z", "diagnostic_id": "diag_project_synthetic_001", "privacy_mode": "minimal" } ], "page": 1, "page_size": 50, "total": 1 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createProject", "summary": "Create a project and its default environments", "description": "Creates one project inside the authenticated organization. The project, its\n`test` and `live` environments, and one `Default` notifier per\nenvironment are one atomic logical resource. Equivalent replay returns\nthe original `201` response without extending idempotency retention.\n", "tags": ["Projects"], "security": [{ "clerkSession": [] }, { "bearerGrant": [] }], "x-required-scopes": ["projects:write"], "x-organization-membership": "required", "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_organization", "operation_id", "key"], "equivalence": "validated_request", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectRequest" }, "examples": { "createProject": { "value": { "name": "Synthetic Alerts", "slug": "synthetic-alerts", "default_locale": "es" } } } } } }, "responses": { "201": { "description": "The complete atomic project bootstrap, or the original resource on equivalent replay.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" }, "examples": { "createdProject": { "value": { "id": "project_synthetic_001", "organization_id": "organization_synthetic_001", "name": "Synthetic Alerts", "slug": "synthetic-alerts", "status": "active", "default_locale": "es", "environments": [ { "id": "environment_synthetic_test_001", "project_id": "project_synthetic_001", "kind": "test", "status": "active", "default_notifier": { "id": "notifier_synthetic_test_default_001", "environment_id": "environment_synthetic_test_001", "display_name": "Default", "status": "active", "is_default": true } }, { "id": "environment_synthetic_live_001", "project_id": "project_synthetic_001", "kind": "live", "status": "active", "default_notifier": { "id": "notifier_synthetic_live_default_001", "environment_id": "environment_synthetic_live_001", "display_name": "Default", "status": "active", "is_default": true } } ], "created_at": "2026-07-28T12:05:00Z", "updated_at": "2026-07-28T12:05:00Z", "diagnostic_id": "diag_project_synthetic_001", "privacy_mode": "minimal" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/projects/{project_id}": { "parameters": [{ "$ref": "#/components/parameters/ProjectId" }], "get": { "operationId": "getProject", "summary": "Read one project in the current organization", "description": "Returns the complete project bootstrap. An absent project and a project\noutside the authenticated organization use the same non-enumerating `404`.\n", "tags": ["Projects"], "security": [ { "clerkSession": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["projects:read"], "x-organization-membership": "required", "responses": { "200": { "description": "The current project and its two environments.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" }, "examples": { "project": { "value": { "id": "project_synthetic_001", "organization_id": "organization_synthetic_001", "name": "Synthetic Alerts", "slug": "synthetic-alerts", "status": "active", "default_locale": "es", "environments": [ { "id": "environment_synthetic_test_001", "project_id": "project_synthetic_001", "kind": "test", "status": "active", "default_notifier": { "id": "notifier_synthetic_test_default_001", "environment_id": "environment_synthetic_test_001", "display_name": "Default", "status": "active", "is_default": true } }, { "id": "environment_synthetic_live_001", "project_id": "project_synthetic_001", "kind": "live", "status": "active", "default_notifier": { "id": "notifier_synthetic_live_default_001", "environment_id": "environment_synthetic_live_001", "display_name": "Default", "status": "active", "is_default": true } } ], "created_at": "2026-07-28T12:05:00Z", "updated_at": "2026-07-28T12:05:00Z", "diagnostic_id": "diag_project_synthetic_001", "privacy_mode": "minimal" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "updateProject", "summary": "Set a project's privacy policy", "description": "Changes profile collection for both project environments. minimal is the\ndefault for new and existing projects. standard permits messenger profiles;\nminimal keeps recipient language only; private keeps delivery routing and\nthe customer-supplied subscriber identifier, with no profile data.\nMoving standard to minimal erases existing identifying profile fields.\nMoving to private also erases recipient language. Increasing collection\ndoes not restore erased data. The operation is naturally idempotent.\nAn absent project and one outside the organization return the same 404.\n", "tags": ["Projects"], "security": [ { "clerkSession": [] }, { "bearerGrant": [] }, { "bearerCredential": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["projects:write"], "x-organization-membership": "required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectRequest" }, "examples": { "updateProject": { "value": { "privacy_mode": "private" } } } } } }, "responses": { "200": { "description": "The project after changing its privacy policy and clearing disallowed profile fields.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/projects/{project_id}/recipient-copy-overrides": { "parameters": [{ "$ref": "#/components/parameters/ProjectId" }], "get": { "operationId": "listRecipientCopyOverrides", "summary": "List sparse recipient-copy overrides for one project", "description": "Returns only customer-authored overrides for the project in the\nauthenticated organization. Missing values are intentionally absent and use\nWhooshBang's complete shipped catalog at render time. An optional\ncanonical language filter preserves the project + language + string\naddress without applying locale negotiation.\n", "tags": ["Projects"], "security": [ { "clerkSession": [] }, { "bearerGrant": [] }, { "bearerCredential": [] } ], "x-required-scopes": ["projects:read"], "x-organization-membership": "required", "parameters": [ { "name": "language", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/RecipientLanguage" } }, { "$ref": "#/components/parameters/ListAfterCursor" }, { "$ref": "#/components/parameters/ListPageLimit" }, { "$ref": "#/components/parameters/PageNumber" } ], "responses": { "200": { "description": "Sparse overrides ordered by language and key.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientCopyOverrideCollection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/projects/{project_id}/recipient-copy-overrides/{language}/{key}": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "name": "language", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/RecipientLanguage" } }, { "name": "key", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/RecipientCopyKey" } } ], "put": { "operationId": "updateRecipientCopyOverride", "summary": "Set one project recipient-copy override", "description": "Replaces the customer-authored plain-text value at one exact project +\nlanguage + string address. Key-specific safety validation rejects\nmarkup, links, controls, impersonation, blank text, and oversized text.\n", "tags": ["Projects"], "security": [ { "clerkSession": [] }, { "bearerGrant": [] }, { "bearerCredential": [] } ], "x-required-scopes": ["projects:write"], "x-organization-membership": "required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRecipientCopyOverrideRequest" } } } }, "responses": { "200": { "description": "The stored override.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientCopyOverride" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "resetRecipientCopyOverride", "summary": "Reset one project recipient-copy override", "description": "Deletes the sparse value at one exact address. Repeating the reset is\nsafe; the shipped catalog is effective immediately whether or not an\noverride existed.\n", "tags": ["Projects"], "security": [ { "clerkSession": [] }, { "bearerGrant": [] }, { "bearerCredential": [] } ], "x-required-scopes": ["projects:write"], "x-organization-membership": "required", "responses": { "204": { "description": "The shipped catalog value is effective at this address." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/credentials": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" } ], "get": { "operationId": "listApiCredentials", "summary": "List safe API credential metadata", "description": "Returns only credentials in the selected project environment owned by\nthe organization selected by the verified Clerk organization session.\nSecrets and digest material are never returned. An absent or\nout-of-organization project or environment uses the same non-enumerating\n`404`.\n", "tags": ["API credentials"], "security": [{ "clerkSession": [] }], "x-organization-membership": "required", "parameters": [ { "$ref": "#/components/parameters/ApiCredentialAfterCursor" }, { "$ref": "#/components/parameters/ApiCredentialPageLimit" }, { "$ref": "#/components/parameters/PageNumber" } ], "responses": { "200": { "description": "A stable page of safe credential metadata.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCredentialCollection" }, "examples": { "credentials": { "value": { "items": [ { "id": "pcred_AAAAAAAAAAAAAAAAAAAAAA", "project_id": "project_synthetic_001", "environment_id": "environment_live_synthetic_001", "environment": "live", "prefix": "wb_pc1.pcred_AAAAAAAA", "label": "Synthetic production integration", "scopes": [ "messages:write", "messages:read", "subscriptions:write", "subscriptions:read" ], "created_by": "member_synthetic_001", "created_at": "2026-07-25T17:45:00Z", "last_used_at": "2026-07-25T17:50:00Z", "status": "active" } ], "page": 1, "page_size": 50, "total": 1 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createApiCredential", "summary": "Create an environment-scoped API credential", "description": "Creates one credential in the selected project environment. The complete\nbearer secret appears only in this creation response. It cannot be read\nlater and is never replayed from an idempotency cache. If a client loses\nthis response, it lists safe metadata and creates then revokes a\nreplacement.\n", "tags": ["API credentials"], "security": [{ "clerkSession": [] }], "x-organization-membership": "required", "x-secret-reveal": { "responses": 1, "replayable": false, "later_reads": "metadata_only" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiCredentialRequest" }, "examples": { "createCredential": { "value": { "label": "Production integration", "scopes": [ "messages:write", "messages:read", "subscriptions:write", "subscriptions:read" ] } } } } } }, "responses": { "201": { "description": "Creation-only secret reveal and safe credential metadata.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCredentialSecretReveal" }, "examples": { "createdCredential": { "value": { "credential": { "id": "pcred_AAAAAAAAAAAAAAAAAAAAAA", "project_id": "project_synthetic_001", "environment_id": "environment_live_synthetic_001", "environment": "live", "prefix": "wb_pc1.pcred_AAAAAAAA", "label": "Synthetic production integration", "scopes": [ "messages:write", "messages:read", "subscriptions:write", "subscriptions:read" ], "created_by": "member_synthetic_001", "created_at": "2026-07-25T17:45:00Z", "status": "active" }, "secret": "wb_pc1.pcred_AAAAAAAAAAAAAAAAAAAAAA.AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/credentials/{credential_id}/rotate": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/ApiCredentialId" } ], "post": { "operationId": "rotateApiCredential", "summary": "Rotate an environment-scoped API credential", "description": "Creates one replacement with the same label and scopes. The complete new\nbearer secret appears only in this response. The replaced credential\nremains active for the explicitly declared overlap, from zero through\n86400 seconds, then becomes terminally revoked. A revoked credential\ncannot be rotated. Missing and out-of-scope credentials use the same\nnon-enumerating `404`.\n", "tags": ["API credentials"], "security": [{ "clerkSession": [] }], "x-organization-membership": "required", "x-secret-reveal": { "responses": 1, "replayable": false, "later_reads": "metadata_only" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateApiCredentialRequest" }, "examples": { "rotateCredential": { "value": { "overlap_seconds": 3600 } } } } } }, "responses": { "201": { "description": "Creation-only replacement secret and safe metadata for both credentials.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCredentialRotation" }, "examples": { "rotatedCredential": { "value": { "credential": { "credential": { "id": "pcred_BBBBBBBBBBBBBBBBBBBBBA", "project_id": "project_synthetic_001", "environment_id": "environment_live_synthetic_001", "environment": "live", "prefix": "wb_pc1.pcred_BBBBBBBB", "label": "Synthetic production integration", "scopes": [ "messages:write", "messages:read", "subscriptions:write", "subscriptions:read" ], "created_by": "member_synthetic_001", "created_at": "2026-07-25T17:45:00Z", "status": "active" }, "secret": "wb_pc1.pcred_BBBBBBBBBBBBBBBBBBBBBA.BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBA" }, "replaced_credential": { "id": "pcred_AAAAAAAAAAAAAAAAAAAAAA", "project_id": "project_synthetic_001", "environment_id": "environment_live_synthetic_001", "environment": "live", "prefix": "wb_pc1.pcred_AAAAAAAA", "label": "Synthetic production integration", "scopes": [ "messages:write", "messages:read", "subscriptions:write", "subscriptions:read" ], "created_by": "member_synthetic_001", "created_at": "2026-07-25T17:45:00Z", "last_used_at": "2026-07-25T17:50:00Z", "scheduled_revocation_at": "2026-07-25T18:45:00Z", "status": "active" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/credentials/{credential_id}/revoke": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/ApiCredentialId" } ], "post": { "operationId": "revokeApiCredential", "summary": "Revoke an environment-scoped API credential", "description": "Immediately and terminally revokes the selected credential. Repeating\nthe request for the same visible credential is safe and returns the\nsame revoked metadata without revealing secret or digest material.\nMissing and out-of-scope credentials use the same non-enumerating `404`.\n", "tags": ["API credentials"], "security": [{ "clerkSession": [] }], "x-organization-membership": "required", "x-repeat-semantics": { "same_target": "idempotent", "secret_returned": false }, "responses": { "200": { "description": "Safe terminal credential metadata.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCredential" }, "examples": { "revokedCredential": { "value": { "id": "pcred_AAAAAAAAAAAAAAAAAAAAAA", "project_id": "project_synthetic_001", "environment_id": "environment_live_synthetic_001", "environment": "live", "prefix": "wb_pc1.pcred_AAAAAAAA", "label": "Synthetic production integration", "scopes": [ "messages:write", "messages:read", "subscriptions:write", "subscriptions:read" ], "created_by": "member_synthetic_001", "created_at": "2026-07-25T17:45:00Z", "last_used_at": "2026-07-25T17:50:00Z", "status": "revoked", "revoked_at": "2026-07-25T17:55:00Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/subscription-links": { "post": { "operationId": "createSubscriptionLink", "summary": "Create a subscription link", "description": "Creates one single-use authorization link inside the authenticated\nproject and environment. Equivalent replay returns the original `201`\nresponse and logical resource without extending idempotency retention.\nA pending Telegram resource returns the selected bot's native `t.me`\nlink directly; it does not route a new authorization through a hosted\nWhooshBang page.\n", "tags": ["Subscription links"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["subscriptions:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_environment", "operation_id", "key"], "equivalence": "validated_request_after_documented_defaults", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionLinkRequest" }, "examples": { "defaultTelegram": { "value": { "subscriber_id": "customer_123", "channels": ["telegram"], "connection_id": "connection_synthetic_telegram_001", "recipient_language": "es", "return_url": "https://example.test/settings/notifications" } } } } } }, "responses": { "201": { "description": "A new link, or the original link and original status on equivalent replay.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionLink" }, "examples": { "pending": { "value": { "id": "slink_synthetic_001", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "customer_123", "notifier_id": "default", "channels": ["telegram"], "recipient_language": "es", "connection": { "id": "connection_synthetic_telegram_001", "mode": "whooshbang_shared", "display_name": "WhooshBang", "identity": { "handle": "WhooshBangSyntheticBot", "provider": "telegram" } }, "status": "pending", "authorization_url": "https://t.me/WhooshBangSyntheticBot?start=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "created_at": "2026-07-25T17:45:00Z", "updated_at": "2026-07-25T17:45:00Z", "expires_at": "2026-07-25T18:00:00Z", "diagnostic_id": "diag_link_pending_001" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/subscription-links/{subscription_link_id}": { "parameters": [{ "$ref": "#/components/parameters/SubscriptionLinkId" }], "get": { "operationId": "getSubscriptionLink", "summary": "Inspect a subscription link", "description": "Returns the current link state. An activated or revoked link exposes an\nopaque binding summary, never a Telegram chat or user identifier.\nCross-project and cross-environment identifiers return `404`.\n", "tags": ["Subscription links"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["subscriptions:read"], "responses": { "200": { "description": "Current link state.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionLink" }, "examples": { "activated": { "value": { "id": "slink_synthetic_001", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "customer_123", "notifier_id": "default", "channels": ["telegram"], "recipient_language": "es", "connection": { "id": "connection_synthetic_telegram_001", "mode": "whooshbang_shared", "display_name": "WhooshBang", "identity": { "handle": "WhooshBangSyntheticBot", "provider": "telegram" } }, "status": "activated", "binding": { "id": "binding_synthetic_001", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "customer_123", "notifier_id": "default", "channel": "telegram", "connection_id": "connection_synthetic_telegram_001", "status": "active" }, "created_at": "2026-07-25T17:45:00Z", "updated_at": "2026-07-25T17:47:00Z", "expires_at": "2026-07-25T18:00:00Z", "diagnostic_id": "diag_link_active_001" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/subscription-links/{subscription_link_id}/cancel": { "parameters": [{ "$ref": "#/components/parameters/SubscriptionLinkId" }], "post": { "operationId": "cancelSubscriptionLink", "summary": "Cancel a pending subscription link", "description": "Cancels a pending link. Equivalent replay returns the original result.\nConsumption of a cancelled or expired link never creates a binding.\n", "tags": ["Subscription links"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["subscriptions:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_environment", "operation_id", "key"], "equivalence": "validated_request_after_documented_defaults", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "responses": { "200": { "description": "Current link state and whether cancellation took effect.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionLink" }, { "type": "object", "required": ["cancellation_effective"] } ] }, "examples": { "cancelled": { "value": { "id": "slink_synthetic_002", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "customer_456", "notifier_id": "default", "channels": ["telegram"], "recipient_language": "es", "connection": { "id": "connection_synthetic_telegram_001", "mode": "whooshbang_shared", "display_name": "WhooshBang", "identity": { "handle": "WhooshBangSyntheticBot", "provider": "telegram" } }, "status": "cancelled", "created_at": "2026-07-25T17:45:00Z", "updated_at": "2026-07-25T17:46:00Z", "expires_at": "2026-07-25T18:00:00Z", "diagnostic_id": "diag_link_cancel_001", "cancellation_effective": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/notification-image-assets": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" } ], "post": { "operationId": "uploadNotificationImageAsset", "summary": "Normalize and retain one environment-owned notification image", "description": "Accepts one bounded raw PNG, validates and re-encodes it as canonical\nRGBA PNG bytes, and retains the immutable asset for a 30-day admission\nwindow. The service never fetches a customer URL. An equivalent replay\nreturns the original asset with `200`; a new asset returns `201`.\n", "tags": ["Messages"], "security": [ { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["messages:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_environment", "operation_id", "key"], "equivalence": "canonical_rgba_png_after_validation", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "image/png": { "schema": { "type": "string", "format": "binary", "maxLength": 524288 } } } }, "responses": { "200": { "description": "The original immutable asset returned on equivalent idempotent replay.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationImageAsset" } } } }, "201": { "description": "A newly retained immutable canonical PNG asset.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationImageAsset" }, "examples": { "uploaded": { "value": { "id": "asset_11111111111111111111111111111111", "content_type": "image/png", "byte_size": 70, "width": 1, "height": 1, "sha256": "1111111111111111111111111111111111111111111111111111111111111111", "created_at": "2026-07-25T17:45:00.000Z", "expires_at": "2026-08-24T17:45:00.000Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/notification-image-assets/{asset_id}": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/NotificationImageAssetId" } ], "delete": { "operationId": "deleteNotificationImageAsset", "summary": "Delete one environment-owned notification image", "description": "Immediately prevents new notification references. Repeating deletion\nof an asset already deleted in this exact scope remains successful;\nunknown and foreign identifiers return the same non-enumerating `404`.\nAccepted notifications retain their existing delivery lease.\n", "tags": ["Messages"], "security": [ { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["messages:write"], "x-repeat-semantics": { "same_target": "idempotent", "secret_returned": false }, "responses": { "204": { "description": "The owned asset is deleted or was already deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/messages": { "post": { "operationId": "createMessage", "summary": "Create an asynchronous message", "description": "Durably accepts one logical text message for one subscriber and one\nresolved channel binding. `202` proves API acceptance only; it does not\nclaim provider acceptance or end-device delivery.\nThe reserved `test:` subscriber prefix and `delivery_target: simulator`\nare test-environment-only. Live sends are refused before acceptance or\nidempotent replay with `400 request_invalid`; reserved subscriber IDs\ncarry a field error at `/to/subscriber_id`.\n", "tags": ["Messages"], "security": [{ "bearerCredential": [] }, { "machineCredential": [] }], "x-required-scopes": ["messages:write"], "x-machine-required-scopes": ["machine-messages:write"], "x-machine-binding-enforcement": [ "authenticated_project", "authenticated_environment", "bound_notifier", "bound_subscriber" ], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_environment", "operation_id", "key"], "equivalence": "validated_request_after_documented_defaults", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMessageRequest" }, "examples": { "text": { "value": { "to": { "subscriber_id": "customer_123" }, "notifier_id": "default", "content": { "type": "text", "text": "Your export is ready." }, "expires_at": "2026-07-25T18:00:00Z", "correlation_id": "export_987", "metadata": { "job": "export_987" } } }, "confirm": { "value": { "to": { "subscriber_id": "agent_relay_operator" }, "notifier_id": "default", "content": { "type": "text", "text": "A deployment is waiting for your decision." }, "interaction": { "type": "confirm", "prompt": "Approve the synthetic deployment?", "confirm_label": "Approve", "deny_label": "Deny", "expires_at": "2026-07-25T18:00:00Z", "correlation_id": "request_confirm_001" } } }, "select": { "value": { "to": { "subscriber_id": "agent_relay_operator" }, "notifier_id": "default", "content": { "type": "text", "text": "Choose a synthetic environment." }, "interaction": { "type": "select", "prompt": "Choose an environment", "options": [ { "value": "staging", "label": "Staging" }, { "value": "production", "label": "Production" } ], "expires_at": "2026-07-25T18:00:00Z", "correlation_id": "request_select_001" } } }, "input": { "value": { "to": { "subscriber_id": "agent_relay_operator" }, "notifier_id": "default", "content": { "type": "text", "text": "A bounded response is required." }, "interaction": { "type": "input", "prompt": "What should happen next?", "expires_at": "2026-07-25T18:00:00Z", "correlation_id": "request_input_001" } } } } } } }, "responses": { "202": { "description": "A newly accepted message, or the original message and status on equivalent replay.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" }, "examples": { "accepted": { "value": { "id": "msg_synthetic_001", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "customer_123", "notifier_id": "default", "binding": { "id": "binding_synthetic_001", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "customer_123", "notifier_id": "default", "channel": "telegram", "status": "active" }, "delivery_target": "simulator", "state": "accepted", "accepted_at": "2026-07-25T17:45:00Z", "updated_at": "2026-07-25T17:45:00Z", "expires_at": "2026-07-26T17:45:00Z", "delivery": { "attempt_count": 0, "highest_proven_provider_state": "none", "retry_scheduled": false }, "diagnostic_id": "diag_message_accept_001", "correlation_id": "export_987", "metadata": { "job": "export_987" } } }, "interactionOpen": { "value": { "id": "msg_interactive_synthetic_001", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "agent_relay_operator", "notifier_id": "default", "binding": { "id": "binding_synthetic_relay", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "agent_relay_operator", "notifier_id": "default", "channel": "telegram", "status": "active" }, "delivery_target": "simulator", "state": "accepted", "accepted_at": "2026-07-25T17:45:00Z", "updated_at": "2026-07-25T17:45:00Z", "expires_at": "2026-07-25T18:00:00Z", "delivery": { "attempt_count": 0, "highest_proven_provider_state": "none", "retry_scheduled": false }, "diagnostic_id": "diag_interactive_message_001", "interaction": { "id": "interaction_synthetic_001", "type": "select", "state": "open", "expires_at": "2026-07-25T18:00:00Z", "correlation_id": "request_select_001" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/messages/{message_id}": { "parameters": [{ "$ref": "#/components/parameters/MessageId" }], "get": { "operationId": "getMessage", "summary": "Inspect a message", "description": "Returns the canonical logical state and highest proven provider state.\n`outcome_unknown` is distinct from retryable and terminal failure and\nnever has an automatic retry scheduled.\n\nWhen the message has an open interaction, the optional bounded `wait`\nholds this read for its canonical terminal state. A wait timeout is a\nsuccessful current-state read, not an error. Terminal interactions and\nmessages without an interaction return immediately. Inspection never\nacknowledges, consumes, retries, replays, or changes delivery.\n", "parameters": [ { "$ref": "#/components/parameters/ResponseInspectionWait" } ], "tags": ["Messages"], "security": [{ "bearerCredential": [] }, { "machineCredential": [] }], "x-required-scopes": ["messages:read"], "x-machine-required-scopes": ["machine-messages:read"], "x-machine-binding-enforcement": [ "authenticated_project", "authenticated_environment", "owning_machine_client" ], "responses": { "200": { "description": "Current message and safe delivery-attempt summary.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" }, "examples": { "providerAccepted": { "value": { "id": "msg_synthetic_001", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "customer_123", "notifier_id": "default", "binding": { "id": "binding_synthetic_001", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "customer_123", "notifier_id": "default", "channel": "telegram", "status": "active" }, "delivery_target": "simulator", "state": "provider_accepted", "accepted_at": "2026-07-25T17:45:00Z", "updated_at": "2026-07-25T17:45:02Z", "expires_at": "2026-07-26T17:45:00Z", "delivery": { "attempt_count": 1, "highest_proven_provider_state": "provider_accepted", "retry_scheduled": false }, "diagnostic_id": "diag_message_provider_001", "correlation_id": "export_987", "metadata": { "job": "export_987" } } }, "outcomeUnknown": { "value": { "id": "msg_synthetic_002", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "customer_456", "notifier_id": "default", "binding": { "id": "binding_synthetic_002", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "customer_456", "notifier_id": "default", "channel": "telegram", "status": "active" }, "delivery_target": "simulator", "state": "outcome_unknown", "accepted_at": "2026-07-25T17:45:00Z", "updated_at": "2026-07-25T17:45:03Z", "expires_at": "2026-07-26T17:45:00Z", "delivery": { "attempt_count": 1, "highest_proven_provider_state": "none", "retry_scheduled": false, "classified_error": { "code": "provider_outcome_unknown", "retryable": false, "detail": "The provider may have accepted the request, but no trustworthy result is available.", "diagnostic_id": "diag_provider_unknown_001" } }, "diagnostic_id": "diag_message_unknown_001", "outcome_guidance": "Delivery may have been accepted by the provider. No automatic retry is scheduled; create a new message explicitly if another attempt is appropriate." } }, "interactionOpen": { "value": { "id": "msg_interactive_synthetic_001", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "agent_relay_operator", "notifier_id": "default", "binding": { "id": "binding_synthetic_relay", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "agent_relay_operator", "notifier_id": "default", "channel": "telegram", "status": "active" }, "delivery_target": "simulator", "state": "accepted", "accepted_at": "2026-07-25T17:45:00Z", "updated_at": "2026-07-25T17:45:00Z", "expires_at": "2026-07-25T18:00:00Z", "delivery": { "attempt_count": 0, "highest_proven_provider_state": "none", "retry_scheduled": false }, "diagnostic_id": "diag_interactive_message_001", "interaction": { "id": "interaction_synthetic_001", "type": "select", "state": "open", "expires_at": "2026-07-25T18:00:00Z", "correlation_id": "request_select_001" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/interactions/{interaction_id}": { "parameters": [{ "$ref": "#/components/parameters/InteractionId" }], "get": { "operationId": "getInteraction", "summary": "Inspect an interaction response", "description": "Returns the same canonical first-terminal-writer interaction summary\nused by message status, signed customer events, and machine events.\nAn answered interaction always retains `answered` and `answered_at`;\n`answer_retained` says whether the typed answer is still present.\n\nThe optional bounded `wait` holds an open interaction read for a\nterminal state. Expiry without resolution returns the current `open`\nsummary successfully and can be immediately re-polled. Inspection is\nread-only and has no effect on any delivery or retention lifecycle.\n", "parameters": [ { "$ref": "#/components/parameters/ResponseInspectionWait" } ], "tags": ["Messages"], "security": [{ "bearerCredential": [] }, { "machineCredential": [] }], "x-required-scopes": ["messages:read"], "x-machine-required-scopes": ["machine-messages:read"], "x-machine-binding-enforcement": [ "authenticated_project", "authenticated_environment", "owning_machine_client" ], "responses": { "200": { "description": "Current canonical interaction state and retained answer.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InteractionSummary" }, "examples": { "open": { "value": { "id": "interaction_synthetic_001", "type": "select", "state": "open", "expires_at": "2026-07-25T18:00:00Z", "correlation_id": "request_select_001" } }, "answeredConfirm": { "value": { "id": "interaction_synthetic_confirm", "type": "confirm", "state": "answered", "expires_at": "2026-07-25T18:00:00Z", "correlation_id": "request_confirm_001", "answered_at": "2026-07-25T17:47:00Z", "answer_retained": true, "answer": true } }, "answeredSelect": { "value": { "id": "interaction_synthetic_select", "type": "select", "state": "answered", "expires_at": "2026-07-25T18:00:00Z", "correlation_id": "request_select_001", "answered_at": "2026-07-25T17:47:00Z", "answer_retained": true, "answer": "approve_opaque" } }, "answeredInput": { "value": { "id": "interaction_synthetic_input", "type": "input", "state": "answered", "expires_at": "2026-07-25T18:00:00Z", "correlation_id": "request_input_001", "answered_at": "2026-07-25T17:47:00Z", "answer_retained": true, "answer": "Operator supplied context" } }, "answeredRedacted": { "value": { "id": "interaction_synthetic_confirm", "type": "confirm", "state": "answered", "expires_at": "2026-07-25T18:00:00Z", "answered_at": "2026-07-25T17:47:00Z", "answer_retained": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/messages/{message_id}/cancel": { "parameters": [{ "$ref": "#/components/parameters/MessageId" }], "post": { "operationId": "cancelMessage", "summary": "Cancel a message before provider-call ownership", "description": "Cancellation is effective only before a worker owns the provider call.\nA race at `sending`, `provider_accepted`, or `outcome_unknown` returns\nthe current state with `cancellation_effective: false` and never claims\nprovider-side deletion.\n", "tags": ["Messages"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["messages:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_environment", "operation_id", "key"], "equivalence": "validated_request_after_documented_defaults", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "responses": { "200": { "description": "Current message state and whether cancellation took effect.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Message" }, { "type": "object", "required": ["cancellation_effective"] } ] }, "examples": { "cancelled": { "value": { "id": "msg_synthetic_003", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "customer_789", "notifier_id": "default", "binding": { "id": "binding_synthetic_003", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "customer_789", "notifier_id": "default", "channel": "telegram", "status": "active" }, "delivery_target": "simulator", "state": "cancelled", "accepted_at": "2026-07-25T17:45:00Z", "updated_at": "2026-07-25T17:45:01Z", "expires_at": "2026-07-26T17:45:00Z", "delivery": { "attempt_count": 0, "highest_proven_provider_state": "none", "retry_scheduled": false }, "diagnostic_id": "diag_message_cancel_001", "cancellation_effective": true } }, "tooLate": { "value": { "id": "msg_synthetic_004", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "customer_999", "notifier_id": "default", "binding": { "id": "binding_synthetic_004", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "customer_999", "notifier_id": "default", "channel": "telegram", "status": "active" }, "delivery_target": "simulator", "state": "sending", "accepted_at": "2026-07-25T17:45:00Z", "updated_at": "2026-07-25T17:45:02Z", "expires_at": "2026-07-26T17:45:00Z", "delivery": { "attempt_count": 1, "highest_proven_provider_state": "none", "retry_scheduled": false }, "diagnostic_id": "diag_message_race_001", "cancellation_effective": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/machine-clients": { "post": { "operationId": "createMachineClient", "summary": "Create a destination-bound machine client", "description": "Creates one machine client in the project/environment selected by the\nproject credential. The notifier, subscriber, and active binding become\nimmutable authorization bounds. The response never contains a readable\nsecret or digest.\nLive environments reject the reserved `test:` subscriber prefix with\n`400 request_invalid` and a field error at `/subscriber_id` before creation.\n", "tags": ["Machine clients"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["machine-clients:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_environment", "operation_id", "key"], "equivalence": "validated_request_after_documented_defaults", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMachineClientRequest" }, "examples": { "localClient": { "value": { "machine_id": "machine_synthetic_a", "notifier_id": "default", "subscriber_id": "agent_relay_operator", "display_name": "Synthetic local machine" } } } } } }, "responses": { "201": { "description": "A new provisioning client or the original client on equivalent replay.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineClient" }, "examples": { "provisioning": { "value": { "id": "machine_client_synthetic_001", "project_id": "project_synthetic", "environment": "test", "machine_id": "machine_synthetic_a", "notifier_id": "default", "subscriber_id": "agent_relay_operator", "binding_id": "binding_synthetic_relay", "display_name": "Synthetic local machine", "status": "provisioning", "scope_summary": [ "machine-messages:write", "machine-messages:read", "machine-events:read", "machine-events:ack" ], "created_at": "2026-07-25T17:40:00Z", "updated_at": "2026-07-25T17:40:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/machine-clients/{machine_client_id}": { "parameters": [{ "$ref": "#/components/parameters/MachineClientId" }], "get": { "operationId": "getMachineClient", "summary": "Inspect machine-client metadata", "description": "Returns only safe metadata inside the authenticated project/environment.\nA client outside that scope is indistinguishable from an absent client.\n", "tags": ["Machine clients"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["machine-clients:read"], "responses": { "200": { "description": "Current machine-client metadata and fixed scope summary.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineClient" }, "examples": { "active": { "value": { "id": "machine_client_synthetic_001", "project_id": "project_synthetic", "environment": "test", "machine_id": "machine_synthetic_a", "notifier_id": "default", "subscriber_id": "agent_relay_operator", "binding_id": "binding_synthetic_relay", "display_name": "Synthetic local machine", "status": "active", "scope_summary": [ "machine-messages:write", "machine-messages:read", "machine-events:read", "machine-events:ack" ], "created_at": "2026-07-25T17:40:00Z", "updated_at": "2026-07-25T17:42:00Z", "last_used_at": "2026-07-25T17:43:00Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/machine-clients/{machine_client_id}/credentials": { "parameters": [{ "$ref": "#/components/parameters/MachineClientId" }], "post": { "operationId": "registerMachineCredential", "summary": "Register a locally generated machine-credential digest", "description": "Registers only the credential ID and SHA-256 digest. The same ID and\ndigest returns existing safe metadata; the same ID with another digest\nconflicts. The first active credential activates a provisioning client.\n", "tags": ["Machine clients"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["machine-clients:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_environment", "operation_id", "key"], "equivalence": "validated_request_after_documented_defaults", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterMachineCredentialRequest" }, "examples": { "digestOnly": { "value": { "credential_id": "mcred_AAECAwQFBgcICQoLDA0ODw", "secret_sha256": "sha256:89c7460452eddff119fea0419e785c74de2ffb139dbe74323aca4a01e198a5dc" } } } } } }, "responses": { "200": { "description": "Existing safe credential metadata on an equivalent registration replay; never secret or digest.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineCredential" }, "examples": { "existing": { "value": { "credential_id": "mcred_AAECAwQFBgcICQoLDA0ODw", "machine_client_id": "machine_client_synthetic_001", "status": "active", "scope_summary": [ "machine-messages:write", "machine-messages:read", "machine-events:read", "machine-events:ack" ], "created_at": "2026-07-25T17:42:00Z", "last_used_at": "2026-07-25T17:43:00Z" } } } } } }, "201": { "description": "Newly registered safe credential metadata; never secret or digest.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineCredential" }, "examples": { "active": { "value": { "credential_id": "mcred_AAECAwQFBgcICQoLDA0ODw", "machine_client_id": "machine_client_synthetic_001", "status": "active", "scope_summary": [ "machine-messages:write", "machine-messages:read", "machine-events:read", "machine-events:ack" ], "created_at": "2026-07-25T17:42:00Z", "last_used_at": "2026-07-25T17:43:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/machine-clients/{machine_client_id}/credentials/{credential_id}/revoke": { "parameters": [ { "$ref": "#/components/parameters/MachineClientId" }, { "$ref": "#/components/parameters/MachineCredentialId" } ], "post": { "operationId": "revokeMachineCredential", "summary": "Revoke a machine credential", "description": "Idempotently ends new authorization by this credential. Rotation\nregisters and smoke-tests a replacement before this operation.\n", "tags": ["Machine clients"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["machine-clients:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_environment", "operation_id", "key"], "equivalence": "validated_request_after_documented_defaults", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "responses": { "200": { "description": "Safe revoked credential metadata.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineCredential" }, "examples": { "revoked": { "value": { "credential_id": "mcred_AAECAwQFBgcICQoLDA0ODw", "machine_client_id": "machine_client_synthetic_001", "status": "revoked", "scope_summary": [ "machine-messages:write", "machine-messages:read", "machine-events:read", "machine-events:ack" ], "created_at": "2026-07-25T17:42:00Z", "last_used_at": "2026-07-25T18:00:00Z", "revoked_at": "2026-07-25T18:30:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/machine-clients/{machine_client_id}/revoke": { "parameters": [{ "$ref": "#/components/parameters/MachineClientId" }], "post": { "operationId": "revokeMachineClient", "summary": "Revoke a machine client", "description": "Idempotently revokes the client and all new credential authorization.\nExisting messages and immutable events are retained under contract.\n", "tags": ["Machine clients"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["machine-clients:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_environment", "operation_id", "key"], "equivalence": "validated_request_after_documented_defaults", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "responses": { "200": { "description": "Safe revoked client metadata.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineClient" }, "examples": { "revoked": { "value": { "id": "machine_client_synthetic_001", "project_id": "project_synthetic", "environment": "test", "machine_id": "machine_synthetic_a", "notifier_id": "default", "subscriber_id": "agent_relay_operator", "binding_id": "binding_synthetic_relay", "display_name": "Synthetic local machine", "status": "revoked", "scope_summary": [ "machine-messages:write", "machine-messages:read", "machine-events:read", "machine-events:ack" ], "created_at": "2026-07-25T17:40:00Z", "updated_at": "2026-07-25T18:30:00Z", "last_used_at": "2026-07-25T18:00:00Z", "revoked_at": "2026-07-25T18:30:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/machine-events": { "get": { "operationId": "pollMachineEvents", "summary": "Long-poll the authenticated machine stream", "description": "Polls only the stream selected by the machine credential. `after` is\nomitted only on the first poll and otherwise must equal the exact\natomically committed cursor returned for this stream. Any other cursor,\nincluding a known issued but uncommitted cursor, fails closed and never\nrewinds. Unacknowledged events may repeat with the same event ID and\ncursor.\n", "tags": ["Machine events"], "security": [{ "machineCredential": [] }], "x-required-scopes": ["machine-events:read"], "x-event-retention": { "minimum_seconds_after_creation": 604800, "extends_interaction_answer_authority": false }, "parameters": [ { "$ref": "#/components/parameters/MachineAfterCursor" }, { "$ref": "#/components/parameters/MachinePollWait" }, { "$ref": "#/components/parameters/MachinePollLimit" } ], "responses": { "200": { "description": "Stable ordered events and the atomically committed cursor.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineEventPollResponse" }, "examples": { "events": { "value": { "schema": "whooshbang.machine-events.v1", "events": [ { "schema": "whooshbang.interaction-event.v1", "id": "event_interaction_confirm_001", "cursor": "mcur_synthetic_001", "type": "interaction.received", "message_id": "msg_interactive_confirm_001", "interaction_id": "interaction_synthetic_confirm", "correlation_id": "request_confirm_001", "answer_retained": true, "response": { "type": "confirm", "value": true }, "channel_context": { "binding_id": "binding_synthetic_relay", "channel": "telegram", "conversation_kind": "private_chat", "display_name": "Synthetic operator" }, "occurred_at": "2026-07-25T17:47:00Z", "expires_at": "2026-07-25T18:00:00Z" }, { "schema": "whooshbang.interaction-event.v1", "id": "event_interaction_select_001", "cursor": "mcur_synthetic_002", "type": "interaction.received", "message_id": "msg_interactive_select_001", "interaction_id": "interaction_synthetic_select", "correlation_id": "request_select_001", "answer_retained": true, "response": { "type": "select", "value": "staging" }, "channel_context": { "binding_id": "binding_synthetic_relay", "channel": "telegram", "conversation_kind": "private_chat", "display_name": "Synthetic operator" }, "occurred_at": "2026-07-25T17:48:00Z", "expires_at": "2026-07-25T18:00:00Z" } ], "committed_cursor": null, "server_time": "2026-07-25T17:50:00Z" } }, "empty": { "value": { "schema": "whooshbang.machine-events.v1", "events": [], "committed_cursor": "mcur_synthetic_002", "server_time": "2026-07-25T17:51:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/machine-events/{event_id}/ack": { "parameters": [{ "$ref": "#/components/parameters/MachineEventId" }], "post": { "operationId": "ackMachineEvent", "summary": "Record a per-event machine acknowledgement", "description": "Records processed or permitted quarantine disposition idempotently.\nThe committed cursor advances only across a contiguous acknowledged\nprefix. Authentication, stream identity, signature, and schema failures\ncannot be quarantined to skip work.\n", "tags": ["Machine events"], "security": [{ "machineCredential": [] }], "x-required-scopes": ["machine-events:ack"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_environment", "operation_id", "key"], "equivalence": "validated_request_after_documented_defaults", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineEventAckRequest" }, "examples": { "processed": { "value": { "cursor": "mcur_synthetic_001", "disposition": "processed", "reason_code": null } }, "quarantined": { "value": { "cursor": "mcur_synthetic_002", "disposition": "quarantined", "reason_code": "consumer.unsupported_version" } } } } } }, "responses": { "200": { "description": "New or existing acknowledgement and current committed position.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineEventAckResponse" }, "examples": { "processed": { "value": { "event_id": "event_interaction_confirm_001", "cursor": "mcur_synthetic_001", "disposition": "processed", "acknowledgement_status": "recorded", "committed_cursor": "mcur_synthetic_001", "advanced": true } }, "outOfOrder": { "value": { "event_id": "event_interaction_select_001", "cursor": "mcur_synthetic_002", "disposition": "processed", "acknowledgement_status": "recorded", "committed_cursor": null, "advanced": false } }, "quarantined": { "value": { "event_id": "event_interaction_select_001", "cursor": "mcur_synthetic_002", "disposition": "quarantined", "reason_code": "consumer.unsupported_version", "acknowledgement_status": "recorded", "committed_cursor": "mcur_synthetic_002", "advanced": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/customer-endpoints": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" } ], "get": { "operationId": "listCustomerEndpoints", "summary": "List safe customer-endpoint health metadata", "tags": ["Customer endpoints"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "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": "createCustomerEndpoint", "summary": "Create an inactive 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": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["messages:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_environment", "operation_id", "key"], "equivalence": "final_normalized_url_and_validated_request", "replay_retention_extends": false }, "x-secret-reveal": { "responses": 1, "replayable": false, "later_reads": "metadata_only" }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerEndpointRequest" }, "examples": { "createEndpoint": { "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 created unverified endpoint and its one-time signing secret.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerEndpointMutationResult" }, "examples": { "created": { "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/projects/{project_id}/environments/{environment_id}/customer-endpoints/{endpoint_id}": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/CustomerEndpointId" } ], "get": { "operationId": "getCustomerEndpoint", "summary": "Read safe lifecycle and health metadata for one endpoint", "tags": ["Customer endpoints"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["messages:read"], "responses": { "200": { "description": "Safe endpoint metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerEndpoint" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/customer-endpoints/{endpoint_id}/verify": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/CustomerEndpointId" } ], "post": { "operationId": "verifyCustomerEndpoint", "summary": "Send a signed challenge and activate the endpoint only after a signed echo", "tags": ["Customer endpoints"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["messages:write"], "responses": { "200": { "description": "Verified active endpoint metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerEndpoint" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/ProviderTerminal" }, "503": { "$ref": "#/components/responses/ProviderRetryable" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/customer-endpoints/{endpoint_id}/rotate": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/CustomerEndpointId" } ], "post": { "operationId": "rotateCustomerEndpoint", "summary": "Create a new signing version with bounded old/new overlap", "tags": ["Customer endpoints"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["messages:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_environment", "operation_id", "key"], "equivalence": "endpoint_and_validated_request", "replay_retention_extends": false }, "x-secret-reveal": { "responses": 1, "replayable": false, "later_reads": "metadata_only" }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateCustomerEndpointRequest" }, "examples": { "rotate": { "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/projects/{project_id}/environments/{environment_id}/customer-endpoints/{endpoint_id}/{action}": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/CustomerEndpointId" }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": ["pause", "resume", "disable"] } } ], "post": { "operationId": "transitionCustomerEndpoint", "summary": "Pause, resume, or terminally disable an endpoint", "tags": ["Customer endpoints"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["messages:write"], "x-repeat-semantics": { "same_target": "idempotent", "secret_returned": false }, "responses": { "200": { "description": "Updated safe endpoint metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerEndpoint" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/customer-endpoints/{endpoint_id}/attempts": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/CustomerEndpointId" } ], "get": { "operationId": "listCustomerEndpointAttempts", "summary": "Inspect protected content-free delivery diagnostics", "tags": ["Customer endpoints"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "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" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/connection-providers": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" } ], "get": { "operationId": "listConnectionProviders", "summary": "List providers, setup modes, and selectable WhooshBang identities", "description": "What a project can connect to and how. `shared_identities` lists the\nWhooshBang-owned identities an environment may select; WhooshBang\noperates their credentials, and no reference to one appears anywhere in\nthis API.\n", "tags": ["Channel connections"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["connections:read"], "responses": { "200": { "description": "Supported providers with their setup modes and lifecycle operations.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionProviderCollection" }, "examples": { "providers": { "value": { "items": [ { "provider": "telegram", "display_name": "Telegram", "setup_modes": [ "whooshbang_shared", "customer_managed", "customer_byok" ], "lifecycle_operations": [ "validate", "provision", "repair", "health", "rotate", "disable", "deprovision", "purge" ], "shared_installation_supported": true, "shared_identities": [ { "id": "prvinst_11111111111111111111111111111111", "display_name": "WhooshBang", "health": "healthy" } ] } ], "total": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/channel-connections": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" } ], "get": { "operationId": "listChannelConnections", "summary": "List this environment's channel connections", "tags": ["Channel connections"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["connections:read"], "parameters": [ { "$ref": "#/components/parameters/ListAfterCursor" }, { "$ref": "#/components/parameters/ListPageLimit" }, { "$ref": "#/components/parameters/PageNumber" } ], "responses": { "200": { "description": "Connections owned by exactly this organization, project, and environment.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelConnectionCollection" }, "examples": { "connections": { "value": { "items": [ { "id": "chcon_11111111111111111111111111111111", "project_id": "project_synthetic_alpha", "environment_id": "environment_test_synthetic_alpha", "environment": "test", "provider": "telegram", "mode": "whooshbang_shared", "display_name": "Test sender", "status": "active", "health": "healthy", "identity": { "provider": "telegram", "handle": "WhooshBang" }, "row_version": 2, "created_at": "2026-08-12T12:00:00.000Z", "updated_at": "2026-08-12T12:05:00.000Z", "health_checked_at": "2026-08-12T12:05:00.000Z", "last_transition_at": "2026-08-12T12:05:00.000Z", "last_transition_reason": "provisioned", "diagnostic_id": "diag_connection_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": "createChannelConnection", "summary": "Select a provider identity for this environment", "description": "Creates a connection in `pending`. An equivalent idempotent replay\nreturns the same connection; different input for the same key returns\n`idempotency_conflict`.\n\n`whooshbang_shared` names a disclosed WhooshBang-owned identity.\n`customer_byok` supplies the customer's own provider credential and\ncarries no identity field: `provider_identity_digest` is unique across\nevery tenant, so an endpoint that digested a client-supplied identity\nwould answer \"already claimed\" for a bot the caller does not own — an\noracle for whether any given bot is connected to WhooshBang by anyone.\nThe identity is derived server-side from a provider-validated `getMe`\non the submitted credential instead.\n\n`customer_managed` supplies no credential at all. Telegram creates a\nbrand new bot on the administrator's own Telegram account and hands WhooshBang\nits token server to server, so the token never reaches a browser, a\nclipboard, this request, or any response. The connection is returned\n`pending` with a `setup` carrying the link the administrator opens and\nthe moment it stops working; poll the connection, or read\n`setup.status`, to follow the attempt. Creating a bot is a person-only\naction, so a connection whose administrator never returns simply\nexpires — and a bot Telegram already created outlives it, because no\nprovider API can delete a bot.\n\nEverything that can go wrong in a managed setup after this call\nreturns is reported on `setup` rather than as a refusal here, because\nby then the connection exists and the failing party is a person this\nrequest has already answered. A lapsed link is `expired`; an attempt\nTelegram or WhooshBang could not complete is `failed` with a\n`failure_reason`. Both are recoverable through\n`restartChannelConnectionSetup` on the same connection.\n\nThe Problem vocabulary is closed, so each refusal reuses a published\ncode and is distinguished by `field_errors[].code`:\n\n- the provider answered and rejected the credential —\n `request_invalid` 400, `provider_credential_invalid` at `/credential`;\n- the identity already has a webhook and `confirm_webhook_takeover` was\n not sent — `request_invalid` 400, `webhook_takeover_required` at\n `/confirm_webhook_takeover`. This is a warning, not a prohibition:\n repeating the request with the confirmation connects the identity\n whoever owns the endpoint it currently delivers to;\n- the webhook it already has belongs to another WhooshBang connection —\n `request_invalid` 400, `whooshbang_connection_takeover_required` at\n `/confirm_webhook_takeover`. Separate from the code above because the\n consequence is separate: confirming this one **disables** the other\n connection, which would otherwise go on reporting itself healthy while\n receiving nothing;\n- the identity is already connected, by this organization or any other —\n `idempotency_conflict` 409, `provider_identity_claimed` at `/`, which\n reports only that the identity the submitted credential proves is in\n use and never that some other identity is;\n- the provider could not be reached and the outcome is genuinely\n unknown — `provider_outcome_unknown` 502, no automatic retry;\n- the provider rate-limited the call — `provider_retryable` 503 with\n `retry_at`.\n", "tags": ["Channel connections"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["connections:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_environment", "operation_id", "key"], "equivalence": "validated_request", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChannelConnectionRequest" }, "examples": { "selectSharedIdentity": { "value": { "mode": "whooshbang_shared", "display_name": "Live sender", "shared_identity_id": "prvinst_11111111111111111111111111111111" } }, "bringYourOwnCredential": { "value": { "mode": "customer_byok", "display_name": "Acme Support Bot", "credential": "0000000000:synthetic-example.not-a-real-bot-token", "confirm_webhook_takeover": true } }, "createBotThroughManagedSetup": { "value": { "mode": "customer_managed", "display_name": "Acme Alerts Bot", "suggested_bot_username": "acme_alerts_bot", "suggested_bot_name": "Acme Alerts" } } } } } }, "responses": { "200": { "description": "Equivalent replay returning the connection that already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelConnection" }, "examples": { "replayed": { "value": { "id": "chcon_22222222222222222222222222222222", "project_id": "project_synthetic_alpha", "environment_id": "environment_live_synthetic_alpha", "environment": "live", "provider": "telegram", "mode": "whooshbang_shared", "display_name": "Live sender", "status": "pending", "health": "unknown", "identity": { "provider": "telegram", "handle": "WhooshBang" }, "row_version": 1, "created_at": "2026-08-12T12:00:00.000Z", "updated_at": "2026-08-12T12:00:00.000Z", "last_transition_at": "2026-08-12T12:05:00.000Z", "last_transition_reason": "created", "diagnostic_id": "diag_connection_create_001" } } } } } }, "201": { "description": "The newly selected connection.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelConnection" }, "examples": { "created": { "value": { "id": "chcon_22222222222222222222222222222222", "project_id": "project_synthetic_alpha", "environment_id": "environment_live_synthetic_alpha", "environment": "live", "provider": "telegram", "mode": "whooshbang_shared", "display_name": "Live sender", "status": "pending", "health": "unknown", "identity": { "provider": "telegram", "handle": "WhooshBang" }, "row_version": 1, "created_at": "2026-08-12T12:00:00.000Z", "updated_at": "2026-08-12T12:00:00.000Z", "last_transition_at": "2026-08-12T12:05:00.000Z", "last_transition_reason": "created", "diagnostic_id": "diag_connection_create_001" } }, "createdFromCustomerCredential": { "value": { "id": "chcon_33333333333333333333333333333333", "project_id": "project_synthetic_alpha", "environment_id": "environment_live_synthetic_alpha", "environment": "live", "provider": "telegram", "mode": "customer_byok", "display_name": "Acme Support Bot", "status": "pending", "health": "unknown", "identity": { "provider": "telegram", "handle": "acme_support_synthetic_bot" }, "row_version": 1, "created_at": "2026-08-12T14:00:00.000Z", "updated_at": "2026-08-12T14:00:00.000Z", "last_transition_at": "2026-08-12T14:00:00.000Z", "last_transition_reason": "credential_validated", "diagnostic_id": "diag_connection_byok_create_001" } }, "awaitingManagedSetup": { "value": { "id": "chcon_44444444444444444444444444444444", "project_id": "project_synthetic_alpha", "environment_id": "environment_live_synthetic_alpha", "environment": "live", "provider": "telegram", "mode": "customer_managed", "display_name": "Acme Alerts Bot", "status": "pending", "health": "unknown", "setup": { "status": "awaiting_handoff", "handoff_url": "https://t.me/whooshbang_setup_bot?start=synthetic-setup-handoff-0001", "expires_at": "2026-08-12T15:15:00.000Z", "suggested_bot_username": "acme_alerts_bot" }, "row_version": 1, "created_at": "2026-08-12T15:00:00.000Z", "updated_at": "2026-08-12T15:00:00.000Z", "last_transition_at": "2026-08-12T15:00:00.000Z", "last_transition_reason": "managed_setup_started", "diagnostic_id": "diag_connection_managed_create_001" } } } } } }, "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" }, "502": { "$ref": "#/components/responses/ProviderOutcomeUnknown" }, "503": { "$ref": "#/components/responses/ProviderRetryable" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/channel-connections/{connection_id}": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/ChannelConnectionId" } ], "get": { "operationId": "getChannelConnection", "summary": "Read one channel connection", "tags": ["Channel connections"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["connections:read"], "responses": { "200": { "description": "The connection, without credential material or any reference to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelConnection" }, "examples": { "awaitingManagedSetup": { "value": { "id": "chcon_44444444444444444444444444444444", "project_id": "project_synthetic_alpha", "environment_id": "environment_live_synthetic_alpha", "environment": "live", "provider": "telegram", "mode": "customer_managed", "display_name": "Acme Alerts Bot", "status": "pending", "health": "unknown", "setup": { "status": "awaiting_handoff", "handoff_url": "https://t.me/whooshbang_setup_bot?start=synthetic-setup-handoff-0001", "expires_at": "2026-08-12T15:15:00.000Z", "suggested_bot_username": "acme_alerts_bot" }, "row_version": 1, "created_at": "2026-08-12T15:00:00.000Z", "updated_at": "2026-08-12T15:00:00.000Z", "last_transition_at": "2026-08-12T15:00:00.000Z", "last_transition_reason": "managed_setup_started", "diagnostic_id": "diag_connection_managed_create_001" } }, "managedSetupFailed": { "value": { "id": "chcon_44444444444444444444444444444444", "project_id": "project_synthetic_alpha", "environment_id": "environment_live_synthetic_alpha", "environment": "live", "provider": "telegram", "mode": "customer_managed", "display_name": "Acme Alerts Bot", "status": "pending", "health": "unknown", "setup": { "status": "failed", "handoff_url": "https://t.me/whooshbang_setup_bot?start=synthetic-setup-handoff-0001", "expires_at": "2026-08-12T15:15:00.000Z", "suggested_bot_username": "acme_alerts_bot", "failure_reason": "A setup is already in progress on that Telegram account. Finish or abandon it, then start this one again." }, "row_version": 2, "created_at": "2026-08-12T15:00:00.000Z", "updated_at": "2026-08-12T15:04:00.000Z", "last_transition_at": "2026-08-12T15:04:00.000Z", "last_transition_reason": "managed_setup_failed", "diagnostic_id": "diag_connection_managed_failed_001" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "updateChannelConnection", "summary": "Rename or enable and disable a connection", "description": "Applies the edit only if `row_version` is still current, so a rename and\na disable made at the same time cannot silently undo each other.\n", "tags": ["Channel connections"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["connections:write"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChannelConnectionRequest" }, "examples": { "rename": { "value": { "row_version": 2, "display_name": "Renamed sender" } } } } } }, "responses": { "200": { "description": "The updated connection with its advanced row version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelConnection" } } } }, "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" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/channel-connections/{connection_id}/email-remediation": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/ChannelConnectionId" } ], "post": { "operationId": "acknowledgeEmailRemediation", "summary": "Acknowledge remediation of a shared email sending hold", "description": "Requires current organization administrator membership through a session\nor an OAuth grant with connections:write. Service credentials cannot\nacknowledge on behalf of an owner. Releases only this organization's\nexisting shared domain hold; revoked recipients and sender state are unchanged.\n", "tags": ["Channel connections"], "security": [{ "clerkSession": [] }, { "bearerGrant": [] }], "x-required-scopes": ["connections:write"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcknowledgeEmailRemediationRequest" } } } }, "responses": { "200": { "description": "The connection after acknowledgement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelConnection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/channel-connections/{connection_id}/archive": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/ChannelConnectionId" } ], "post": { "operationId": "archiveChannelConnection", "summary": "Retire a connection permanently", "description": "Archiving is terminal and removes the connection's notifier routing.\nReconnecting later is a new connection, so consent a subscriber gave to\nthe archived identity is never revived under it. A shared identity other\nenvironments still use is untouched.\n", "tags": ["Channel connections"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["connections:write"], "responses": { "200": { "description": "The archived connection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelConnection" }, "examples": { "archived": { "value": { "id": "chcon_11111111111111111111111111111111", "project_id": "project_synthetic_alpha", "environment_id": "environment_test_synthetic_alpha", "environment": "test", "provider": "telegram", "mode": "whooshbang_shared", "display_name": "Test sender", "status": "archived", "health": "healthy", "identity": { "provider": "telegram", "handle": "WhooshBang" }, "row_version": 3, "created_at": "2026-08-12T12:00:00.000Z", "updated_at": "2026-08-12T13:00:00.000Z", "health_checked_at": "2026-08-12T12:05:00.000Z", "last_transition_at": "2026-08-12T13:00:00.000Z", "last_transition_reason": "owner_archived", "diagnostic_id": "diag_connection_archive_001", "archived_at": "2026-08-12T13:00:00.000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/channel-connections/{connection_id}/repair": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/ChannelConnectionId" } ], "post": { "operationId": "repairChannelConnection", "summary": "Reprovision a connection that stopped receiving", "description": "Re-establishes the provider-side delivery path for a connection whose\nidentity is unchanged — most often a webhook that something else\noverwrote. The identity a subscriber consented to is never replaced, so\nrepair recovers a `degraded` connection without asking anyone to\nconsent again.\n\nRepair takes no body: the credential already in custody is what it\nreprovisions with. Supply a replacement credential through\n`rotateChannelConnectionCredential` instead.\n\nRefusals reuse the closed Problem vocabulary and differ by\n`field_errors[].code`:\n\n- the connection is archived, so there is nothing to reprovision —\n `idempotency_conflict` 409, `invalid_connection_transition` at `/`;\n- the credential in custody no longer works — `request_invalid` 400,\n `provider_credential_invalid` at `/credential`, which is a rotation,\n not a repair;\n- the identity acquired a webhook belonging to somebody else and no\n takeover was confirmed on this connection — `request_invalid` 400,\n `webhook_takeover_required` at `/confirm_webhook_takeover`;\n- the provider could not be reached — `provider_outcome_unknown` 502;\n- the provider rate-limited the call — `provider_retryable` 503 with\n `retry_at`.\n", "tags": ["Channel connections"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["connections:write"], "responses": { "200": { "description": "The reprovisioned connection with its advanced row version.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelConnection" }, "examples": { "repaired": { "value": { "id": "chcon_33333333333333333333333333333333", "project_id": "project_synthetic_alpha", "environment_id": "environment_live_synthetic_alpha", "environment": "live", "provider": "telegram", "mode": "customer_byok", "display_name": "Acme Support Bot", "status": "active", "health": "healthy", "identity": { "provider": "telegram", "handle": "acme_support_synthetic_bot" }, "row_version": 3, "created_at": "2026-08-12T14:00:00.000Z", "updated_at": "2026-08-12T14:20:00.000Z", "health_checked_at": "2026-08-12T14:20:00.000Z", "last_transition_at": "2026-08-12T14:20:00.000Z", "last_transition_reason": "webhook_reprovisioned", "diagnostic_id": "diag_connection_repair_001" } } } } } }, "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" }, "502": { "$ref": "#/components/responses/ProviderOutcomeUnknown" }, "503": { "$ref": "#/components/responses/ProviderRetryable" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/channel-connections/{connection_id}/reauthorize": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/ChannelConnectionId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "post": { "operationId": "reauthorizeChannelConnection", "summary": "Reinstall a hosted connection through its provider", "description": "Starts a fresh Slack OAuth installation for this exact hosted\nconnection. The returned resource carries durable authorization\nprogress in `authorization_setup`, so a caller can resume it after a\nreload or lost response. Completion is accepted only for the workspace\nalready bound to the connection; a different workspace fails closed.\n\nThe authorization code is exchanged by WhooshBang. It is never copied\ninto this request or returned by any API surface.\n", "tags": ["Channel connections"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["connections:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_environment", "operation_id", "key"], "equivalence": "selected_connection", "replay_retention_extends": false }, "responses": { "200": { "description": "The equivalent durable authorization attempt already in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelConnection" } } } }, "201": { "description": "A new authorization attempt for the exact selected connection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelConnection" } } } }, "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" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/channel-connections/{connection_id}/restart-setup": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/ChannelConnectionId" } ], "post": { "operationId": "restartChannelConnectionSetup", "summary": "Start a fresh setup on a connection that never finished one", "description": "Issues a new guided setup for a `customer_managed` connection whose\nsetup expired, failed, or was simply abandoned. Nothing was ever\nprovisioned under it, no identity was claimed, and no subscriber ever\nconsented to anything through it, so nothing is lost.\n\n**Telegram reuses the connection and answers `200`.** A fresh `setup`\nappears on the same resource.\n\n**Customer-owned Slack replaces the connection and answers `201`.** The\nabandoned connection is archived and a new one is returned, carrying a\nnew `app_setup` and a new creation link. The connection cannot be\nreused, because Slack bakes this deployment's request URLs into the app\nat the moment it is created and they are not ours to change afterwards:\na second setup on one connection would mean two Slack apps answering to\none address. **Read `id` on the response** — the connection you were\npolling is now archived. A Slack app the previous attempt already\ncreated is not withdrawn and cannot be; it is the customer's, and they\ndelete it in Slack when they are ready.\n\nEntering the three app-specific values again is not a restart, and does\nnot need one. `rotate-credential` replaces them on the connection that\nalready exists.\n\nRestart takes no body. The suggested identity recorded when the\nconnection was created is what the new attempt proposes again, so a\ncaller resuming a half-finished setup cannot accidentally rename a bot\nan administrator was already looking at. A different suggestion means\na different connection.\n\nRepeating the call is safe. A setup that is still live is returned as\nit stands rather than being replaced, so two dashboard tabs converge\non one session instead of racing to strand each other's link, and only\na session that can no longer be used is exchanged for a new one.\n\nA bot the previous attempt already created is not withdrawn and cannot\nbe: Telegram exposes no way to delete a bot. The administrator keeps it\nin their own Telegram account until they retire it in BotFather, and a restart\nwalks them through creating another rather than pretending the first\nnever happened.\n\nRefusals reuse the closed Problem vocabulary and differ by\n`field_errors[].code`:\n\n- the connection did not come from guided setup, so there is no setup\n to restart — `idempotency_conflict` 409, `setup_not_managed` at `/`;\n- the connection already finished setup, or is archived, so restarting\n would offer a second identity for something subscribers may already\n be bound to — `idempotency_conflict` 409,\n `invalid_connection_transition` at `/`;\n- the provider could not be reached, so whether a new session exists is\n genuinely unknown — `provider_outcome_unknown` 502; read the\n connection before calling again;\n- the provider rate-limited the call — `provider_retryable` 503 with\n `retry_at`.\n", "tags": ["Channel connections"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["connections:write"], "x-repeat-semantics": { "same_target": "idempotent", "secret_returned": false }, "responses": { "200": { "description": "The connection carrying a usable setup and its advanced row version.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelConnection" }, "examples": { "setupRestarted": { "value": { "id": "chcon_44444444444444444444444444444444", "project_id": "project_synthetic_alpha", "environment_id": "environment_live_synthetic_alpha", "environment": "live", "provider": "telegram", "mode": "customer_managed", "display_name": "Acme Alerts Bot", "status": "pending", "health": "unknown", "setup": { "status": "awaiting_handoff", "handoff_url": "https://t.me/whooshbang_setup_bot?start=synthetic-setup-handoff-0002", "expires_at": "2026-08-12T15:25:00.000Z", "suggested_bot_username": "acme_alerts_bot" }, "row_version": 3, "created_at": "2026-08-12T15:00:00.000Z", "updated_at": "2026-08-12T15:10:00.000Z", "last_transition_at": "2026-08-12T15:10:00.000Z", "last_transition_reason": "managed_setup_restarted", "diagnostic_id": "diag_connection_managed_restart_001" } } } } } }, "201": { "description": "A replacement connection carrying a fresh setup, for a\ncustomer-owned Slack app whose request URLs cannot be re-pointed.\nThe connection named in the request is now archived.\n", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelConnection" }, "examples": { "setupReplaced": { "value": { "id": "chcon_77777777777777777777777777777777", "project_id": "project_synthetic_alpha", "environment_id": "environment_test_synthetic_alpha", "environment": "test", "provider": "slack", "mode": "customer_managed", "display_name": "Acme Slack", "status": "pending", "health": "unknown", "installation": { "display_name": "Slack app not yet created", "health": "unknown", "status": "pending" }, "capabilities": [], "recovery_action": "complete_authorization", "app_setup": { "status": "awaiting_authorities", "creation_url": "https://api.slack.com/apps?new_app=1&manifest_json=%7B%22_metadata%22%3A%7B%22major_version%22%3A1%7D%7D", "expires_at": "2026-09-01T12:30:00.000Z", "app_name": "Acme Notifications", "bot_display_name": "Acme Notify", "outstanding_authorities": [ "application_identity", "application_secret", "ingress_secret" ] }, "row_version": 1, "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "last_transition_at": "2026-09-01T12:00:00.000Z", "last_transition_reason": "slack_setup_awaiting_authorities", "diagnostic_id": "diag_slack_customer_pending_001" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "502": { "$ref": "#/components/responses/ProviderOutcomeUnknown" }, "503": { "$ref": "#/components/responses/ProviderRetryable" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/channel-connections/{connection_id}/rotate-credential": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/ChannelConnectionId" } ], "post": { "operationId": "rotateChannelConnectionCredential", "summary": "Replace the credential behind a customer-owned connection", "description": "Seals a replacement credential and reprovisions delivery with it. The\nconnection keeps its provider identity, so every subscriber stays bound\nto the identity it consented to and only the secret changes.\n\nWhere the replacement comes from is decided by the connection, not by\nthe caller's preference. A `customer_byok` connection sends\n`credential`, because only its owner can produce a replacement. A\n`customer_managed` connection sends `{\"source\": \"provider_managed\"}`\nand nothing else, because only Telegram can issue one: asked to\nrotate, it revokes the bot's current token and hands the successor to\nthe manager that created it, so there is no customer-supplied\ncredential to send and no field here to send it in.\n\nA provider-managed rotation is one-shot. Once the replace call may have\nreached Telegram, an unconfirmed outcome is resolved by asking Telegram\nfor the bot's current token rather than by replacing again, because a\nsecond replace would revoke the token the first one issued. That is why\n`provider_outcome_unknown` on this operation is an instruction to read\nthe connection, never a hint to repeat the call.\n\nThe replacement must prove the same identity. A credential for a\ndifferent bot is a different identity and therefore a different\nconnection, which is why it is refused rather than silently\nre-pointing an existing connection — and the refusal names only the\nconnection's own identity, never anyone else's.\n\nRefusals reuse the closed Problem vocabulary and differ by\n`field_errors[].code`:\n\n- the provider answered and rejected the replacement —\n `request_invalid` 400, `provider_credential_invalid` at `/credential`;\n- the arm does not match how this connection holds its credential —\n `request_invalid` 400, `rotation_source_mismatch`, at `/credential`\n when a `customer_managed` connection was sent a customer credential\n and at `/source` when a `customer_byok` connection was asked for a\n provider-issued one;\n- the replacement proves a different identity — `request_invalid` 400,\n `provider_identity_mismatch` at `/credential`;\n- the connection is `whooshbang_shared`, whose credential WhooshBang\n operates — `idempotency_conflict` 409,\n `credential_not_customer_owned` at `/`;\n- the connection is archived — `idempotency_conflict` 409,\n `invalid_connection_transition` at `/`;\n- the connection's own identity cannot be established, so no\n replacement can be proved to belong to it — `idempotency_conflict`\n 409, `provider_identity_unverifiable` at `/`. Reachable only for a\n connection that recorded no identity and whose stored credential no\n longer validates; the remedy is to archive it and connect again,\n because rotating without that proof is exactly the silent move of a\n subscriber's consent this operation exists to prevent;\n- the provider could not be reached — `provider_outcome_unknown` 502,\n so the caller must read the connection before retrying;\n- the provider rate-limited the call — `provider_retryable` 503 with\n `retry_at`.\n", "tags": ["Channel connections"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["connections:write"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateChannelConnectionCredentialRequest" }, "examples": { "rotate": { "value": { "credential": "0000000000:synthetic-example.rotated-not-a-real-bot-token" } }, "rotateProviderManaged": { "value": { "source": "provider_managed" } } } } } }, "responses": { "200": { "description": "The connection running on the replacement credential.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelConnection" }, "examples": { "rotated": { "value": { "id": "chcon_33333333333333333333333333333333", "project_id": "project_synthetic_alpha", "environment_id": "environment_live_synthetic_alpha", "environment": "live", "provider": "telegram", "mode": "customer_byok", "display_name": "Acme Support Bot", "status": "active", "health": "healthy", "identity": { "provider": "telegram", "handle": "acme_support_synthetic_bot" }, "row_version": 4, "created_at": "2026-08-12T14:00:00.000Z", "updated_at": "2026-08-12T14:30:00.000Z", "health_checked_at": "2026-08-12T14:30:00.000Z", "last_transition_at": "2026-08-12T14:30:00.000Z", "last_transition_reason": "credential_rotated", "diagnostic_id": "diag_connection_rotate_001" } }, "rotatedProviderManaged": { "value": { "id": "chcon_44444444444444444444444444444444", "project_id": "project_synthetic_alpha", "environment_id": "environment_live_synthetic_alpha", "environment": "live", "provider": "telegram", "mode": "customer_managed", "display_name": "Acme Alerts Bot", "status": "active", "health": "healthy", "identity": { "provider": "telegram", "handle": "acme_alerts_bot" }, "row_version": 6, "created_at": "2026-08-12T15:00:00.000Z", "updated_at": "2026-08-12T16:00:00.000Z", "health_checked_at": "2026-08-12T16:00:00.000Z", "last_transition_at": "2026-08-12T16:00:00.000Z", "last_transition_reason": "credential_rotated", "diagnostic_id": "diag_connection_managed_rotate_001" } } } } } }, "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" }, "502": { "$ref": "#/components/responses/ProviderOutcomeUnknown" }, "503": { "$ref": "#/components/responses/ProviderRetryable" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/channel-connections/{connection_id}/health-check": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/ChannelConnectionId" } ], "post": { "operationId": "checkChannelConnectionHealth", "summary": "Re-check a connection against the provider now", "description": "Asks the provider about this connection and records the answer in\n`health` and `health_checked_at`. A connection whose delivery path\ndiverged becomes `degraded`, which still delivers: the identity a\nsubscriber consented to has not changed, only its last health check.\n\nThis is `connections:write` rather than `connections:read` on purpose.\nIt makes a live provider call and advances the connection's recorded\nhealth, so it is not a safe read: it is rate-limited by the provider,\nit can fail, and repeating it is not free. Read `health` from\n`getChannelConnection` when the last recorded answer is enough.\n\nRefusals reuse the closed Problem vocabulary and differ by\n`field_errors[].code`:\n\n- the connection is archived, so there is nothing left to check —\n `idempotency_conflict` 409, `invalid_connection_transition` at `/`;\n- the provider could not be reached, so health is genuinely unknown\n rather than bad — `provider_outcome_unknown` 502, and the recorded\n health is left as it was;\n- the provider rate-limited the call — `provider_retryable` 503 with\n `retry_at`.\n", "tags": ["Channel connections"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["connections:write"], "responses": { "200": { "description": "The connection carrying the health the provider just reported.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelConnection" }, "examples": { "healthChecked": { "value": { "id": "chcon_33333333333333333333333333333333", "project_id": "project_synthetic_alpha", "environment_id": "environment_live_synthetic_alpha", "environment": "live", "provider": "telegram", "mode": "customer_byok", "display_name": "Acme Support Bot", "status": "degraded", "health": "degraded", "identity": { "provider": "telegram", "handle": "acme_support_synthetic_bot" }, "row_version": 5, "created_at": "2026-08-12T14:00:00.000Z", "updated_at": "2026-08-12T14:40:00.000Z", "health_checked_at": "2026-08-12T14:40:00.000Z", "last_transition_at": "2026-08-12T14:40:00.000Z", "last_transition_reason": "webhook_url_diverged", "diagnostic_id": "diag_connection_health_001" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "502": { "$ref": "#/components/responses/ProviderOutcomeUnknown" }, "503": { "$ref": "#/components/responses/ProviderRetryable" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/channel-connections/{connection_id}/purge": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/ChannelConnectionId" } ], "post": { "operationId": "purgeChannelConnection", "summary": "Destroy this connection's custody and hand the identity back", "description": "Releases the provider-side delivery path this connection installed and\ndestroys what it holds, then archives it. For `customer_byok` that is\nthe sealed customer credential, so the customer's bot is fully handed\nback and WhooshBang retains nothing that could act as it. A\n`whooshbang_shared` connection owns no credential, so purge releases\nonly its own routing and never touches the shared identity other\nenvironments still use.\n\nPurge is repeat-safe. Destroying something that is already destroyed\nreturns the same archived connection rather than a conflict, because a\ncaller that lost the response to the first attempt must be able to\nconfirm the outcome. Archiving first is not required, and archiving\nafterwards is refused because the connection is already archived.\n\nRefusals reuse the closed Problem vocabulary:\n\n- the provider could not be reached, so whether the delivery path was\n released is genuinely unknown — `provider_outcome_unknown` 502, and\n the connection is left as it was so the call can be repeated;\n- the provider rate-limited the call — `provider_retryable` 503 with\n `retry_at`.\n", "tags": ["Channel connections"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["connections:write"], "responses": { "200": { "description": "The purged connection, archived and holding nothing.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelConnection" }, "examples": { "purged": { "value": { "id": "chcon_33333333333333333333333333333333", "project_id": "project_synthetic_alpha", "environment_id": "environment_live_synthetic_alpha", "environment": "live", "provider": "telegram", "mode": "customer_byok", "display_name": "Acme Support Bot", "status": "archived", "health": "unknown", "identity": { "provider": "telegram", "handle": "acme_support_synthetic_bot" }, "row_version": 6, "created_at": "2026-08-12T14:00:00.000Z", "updated_at": "2026-08-12T14:50:00.000Z", "health_checked_at": "2026-08-12T14:40:00.000Z", "last_transition_at": "2026-08-12T14:50:00.000Z", "last_transition_reason": "owner_purged", "diagnostic_id": "diag_connection_purge_001", "archived_at": "2026-08-12T14:50:00.000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/ProviderOutcomeUnknown" }, "503": { "$ref": "#/components/responses/ProviderRetryable" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/channel-connections/{connection_id}/app-manifest": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/ChannelConnectionId" } ], "get": { "operationId": "getChannelConnectionAppManifest", "summary": "Read the generated application configuration a customer-owned setup will create", "description": "Returns the exact configuration WhooshBang generated for this setup of\nan application the customer creates and owns — the scopes it will ask\nfor, the request URLs it will point at, the literal configuration\ndocument in the provider's own format, and the same prefilled creation\nlink the setup already carries.\n\nIt exists so the owner can read what they are about to approve, and a\nreviewer can check it, without opening the provider or decoding a URL.\nIt carries configuration only: no organization, project, or\nenvironment, no credential, and no provider-native identifier.\n\nOnly a connection whose provider sets it up through an application the\ncustomer creates has one. Every other provider and mode answers `404`,\nbecause a manifest they do not have is not a manifest that is empty.\n", "tags": ["Channel connections"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["connections:read"], "responses": { "200": { "description": "The generated application configuration for exactly this setup.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerApplicationManifest" }, "examples": { "manifest": { "value": { "provider": "slack", "creation_url": "https://api.slack.com/apps?new_app=1&manifest_json=%7B%22_metadata%22%3A%7B%22major_version%22%3A1%7D%7D", "app_name": "Acme Notifications", "bot_display_name": "Acme Notify", "description": "Delivery notifications from Acme.", "bot_scopes": ["chat:write"], "user_scopes": ["openid"], "request_urls": { "events": "https://api.whooshbang.com/internal/webhooks/slack/apps/CTBQNURSpqxDgLcqvbEDcA/events", "interactions": "https://api.whooshbang.com/internal/webhooks/slack/apps/CTBQNURSpqxDgLcqvbEDcA/interactions", "installation_redirect": "https://api.whooshbang.com/v1/provider-authorizations/slack/apps/callback", "recipient_redirect": "https://api.whooshbang.com/v1/provider-authorizations/slack/apps/recipient/callback" }, "manifest": { "_metadata": { "major_version": 1, "minor_version": 1 }, "display_information": { "name": "Acme Notifications", "description": "Delivery notifications from Acme." }, "features": { "app_home": { "home_tab_enabled": true, "messages_tab_enabled": true, "messages_tab_read_only_enabled": true }, "bot_user": { "display_name": "Acme Notify", "always_online": false } }, "oauth_config": { "pkce_enabled": false, "redirect_urls": [ "https://api.whooshbang.com/v1/provider-authorizations/slack/apps/callback", "https://api.whooshbang.com/v1/provider-authorizations/slack/apps/recipient/callback" ], "scopes": { "bot": ["chat:write"], "user": ["openid"] } }, "settings": { "event_subscriptions": { "request_url": "https://api.whooshbang.com/internal/webhooks/slack/apps/CTBQNURSpqxDgLcqvbEDcA/events", "bot_events": [ "app_home_opened", "app_uninstalled", "tokens_revoked" ] }, "interactivity": { "is_enabled": true, "request_url": "https://api.whooshbang.com/internal/webhooks/slack/apps/CTBQNURSpqxDgLcqvbEDcA/interactions" }, "is_hosted": false, "is_mcp_enabled": false, "org_deploy_enabled": false, "socket_mode_enabled": false, "token_rotation_enabled": true } }, "diagnostic_id": "diag_slack_app_manifest_001" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/channel-connections/{connection_id}/tests": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/ChannelConnectionId" } ], "get": { "operationId": "listConnectionTests", "summary": "List this connection's recent owner-triggered tests", "description": "Newest first. This is the audit-safe failure history for one\nconnection: what was tried, when, what came back, and what to do about\nit. Every entry is safe to render, log, and paste into an issue.\n", "tags": ["Channel connections"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["connections:read"], "parameters": [ { "$ref": "#/components/parameters/ListAfterCursor" }, { "$ref": "#/components/parameters/ListPageLimit" }, { "$ref": "#/components/parameters/PageNumber" } ], "responses": { "200": { "description": "Tests placed against exactly this connection.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionTestCollection" }, "examples": { "tests": { "value": { "items": [ { "id": "cntest_11111111111111111111111111111111", "connection_id": "chcon_77777777777777777777777777777777", "kind": "signed_interaction", "status": "succeeded", "requested_at": "2026-09-02T09:00:00.000Z", "completed_at": "2026-09-02T09:00:22.000Z", "expires_at": "2026-09-02T09:15:00.000Z", "evidence": { "identity_handle": "Acme Notify", "workspace_display_name": "Acme", "accepted_at": "2026-09-02T09:00:01.000Z", "observed_at": "2026-09-02T09:00:22.000Z", "round_trip_ms": 22000, "signature_verified": true, "ingress_host": "api.whooshbang.com" }, "recovery_action": "none", "diagnostic_id": "diag_connection_test_succeeded_001" }, { "id": "cntest_22222222222222222222222222222222", "connection_id": "chcon_77777777777777777777777777777777", "kind": "outbound_notification", "status": "failed", "requested_at": "2026-09-02T08:40:00.000Z", "completed_at": "2026-09-02T08:40:02.000Z", "expires_at": "2026-09-02T08:55:00.000Z", "failure_code": "credential_unavailable", "recovery_action": "reinstall", "diagnostic_id": "diag_connection_test_failed_001" } ], "page": 1, "page_size": 25, "total": 2 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "createConnectionTest", "summary": "Prove this exact connection still works", "description": "Runs one test against one connection, on demand, and answers with what\nit observed rather than with a claim.\n\nAvailable on any Slack connection, whether the app is one the customer\nowns or the one WhooshBang operates. Every other provider and mode is\nrefused rather than reporting a pass it never ran.\n\n**A test addresses the workspace member who authorized this exact\nconnection, and nobody else.** For an app the customer owns that is the\nperson who installed it, once, for one connection. The\nWhooshBang-operated app's installation is shared across tenants, so\n\"whoever installed the app\" is not necessarily anybody the calling\ntenant named; what is recorded instead is the member who approved this\nenvironment's own connection, during its own authorization, and each\nlater authorization replaces it. One tenant therefore cannot cause a\nmessage to somebody another tenant authorized.\n\n`outbound_notification` sends one visible private message through this\nexact identity to that member, and settles when the provider accepts\nit. Nobody else can be addressed: a test cannot reach a channel, and it\ncannot reach a subscriber who has not authorized anything.\n\n`signed_interaction` sends that person a message with one button and\nthen waits. It settles when the provider calls this deployment's\ninteractivity URL and the signature over the untouched body verifies\nagainst the secret this connection custodies — the only proof that the\nsigning secret, the request URL, and public reachability are all\ncorrect at once. A window that closes with nothing arriving settles as\n`expired`, which says nobody pressed it, and a request that arrives and\ndoes not verify settles as `failed` with `unverified_request_received`.\n\nThe response is the placed test. An `outbound_notification` is usually\nalready settled when it returns; a `signed_interaction` is `pending`\nuntil somebody presses the button, so read it again or list this\nconnection's tests.\n\n**A provider failure is an answer, not a refusal.** If the connection\nhas not finished setup, or its grant is unavailable, or Slack refuses,\nrate-limits, or cannot be reached, the test is **recorded** and answers\n`201` carrying `status: failed`, a `failure_code` and a\n`recovery_action`. There is no `502` or `503` on this operation, and\nthat is deliberate: a diagnostic that leaves no trace is the one thing\nan audit-safe failure history cannot have, so the failure goes in the\nhistory rather than into a problem document nobody keeps.\n\nThree things are refused outright, because none describes a test that\nran: the connection is archived, it is not a Slack connection, or it is\na WhooshBang-operated Slack connection whose authorization has been\nrevoked — `idempotency_conflict` 409, `invalid_connection_transition`\nat `/`. A connection that has never recorded who authorized it is not\nrefused: it is a recorded failure with\n`verification_target_unknown`, because there is nobody a test could\nhonestly address.\n\nA test never carries customer notification content, never counts as a\ndelivery to a subscriber, and never changes what any subscriber\nreceives.\n", "tags": ["Channel connections"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["connections:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_environment", "operation_id", "key"], "equivalence": "exact_request_body", "replay_retention_extends": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConnectionTestRequest" }, "examples": { "signedInteraction": { "value": { "kind": "signed_interaction" } } } } } }, "responses": { "200": { "description": "The equivalent test an idempotent replay already placed.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionTest" } } } }, "201": { "description": "The placed test, settled if it could settle immediately.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionTest" }, "examples": { "pending": { "value": { "id": "cntest_11111111111111111111111111111111", "connection_id": "chcon_77777777777777777777777777777777", "kind": "signed_interaction", "status": "pending", "requested_at": "2026-09-02T09:00:00.000Z", "expires_at": "2026-09-02T09:15:00.000Z", "evidence": { "identity_handle": "Acme Notify", "workspace_display_name": "Acme", "accepted_at": "2026-09-02T09:00:01.000Z", "ingress_host": "api.whooshbang.com" }, "recovery_action": "none", "diagnostic_id": "diag_connection_test_pending_001" } } } } } }, "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" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/channel-connections/{connection_id}/tests/{test_id}": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/ChannelConnectionId" }, { "$ref": "#/components/parameters/ConnectionTestId" } ], "get": { "operationId": "getConnectionTest", "summary": "Read one owner-triggered connection test", "description": "The durable answer to one test. A `signed_interaction` is read again\nhere until it settles; a pending test whose window has closed reads as\n`expired` on the way out rather than waiting for a sweep, so the status\nthe owner sees is the one they actually have.\n", "tags": ["Channel connections"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["connections:read"], "responses": { "200": { "description": "The exact test.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionTest" }, "examples": { "succeeded": { "value": { "id": "cntest_11111111111111111111111111111111", "connection_id": "chcon_77777777777777777777777777777777", "kind": "signed_interaction", "status": "succeeded", "requested_at": "2026-09-02T09:00:00.000Z", "completed_at": "2026-09-02T09:00:22.000Z", "expires_at": "2026-09-02T09:15:00.000Z", "evidence": { "identity_handle": "Acme Notify", "workspace_display_name": "Acme", "accepted_at": "2026-09-02T09:00:01.000Z", "observed_at": "2026-09-02T09:00:22.000Z", "round_trip_ms": 22000, "signature_verified": true, "ingress_host": "api.whooshbang.com" }, "recovery_action": "none", "diagnostic_id": "diag_connection_test_succeeded_001" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/notifier-connections": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" } ], "get": { "operationId": "listNotifierConnections", "summary": "Read which connection each notifier sends through", "description": "Every route in this environment, ordered by notifier and then\nconnection.\n\nA connection nothing routes to is configured and inert: it delivers\nnothing and a subscriber cannot authorize against it either. This list\nis therefore the answer to \"my connection is active, so why is nothing\narriving?\" — an environment with connections and no default route is\nthe ordinary shape of that question.\n", "tags": ["Channel connections"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["connections:read"], "parameters": [ { "$ref": "#/components/parameters/ListAfterCursor" }, { "$ref": "#/components/parameters/ListPageLimit" }, { "$ref": "#/components/parameters/PageNumber" } ], "responses": { "200": { "description": "Routes owned by exactly this organization, project, and environment.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotifierConnectionCollection" }, "examples": { "routes": { "value": { "items": [ { "notifier_id": "default", "connection_id": "chcon_11111111111111111111111111111111", "is_default": true }, { "notifier_id": "default", "connection_id": "chcon_22222222222222222222222222222222", "is_default": false } ], "total": 2, "page": 1, "page_size": 50 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "attachNotifierConnection", "summary": "Route a notifier through a connection", "description": "Points a notifier at a connection in the same environment and, unless\ntold otherwise, makes it the default the notifier sends and authorizes\nthrough.\n\nRepeating an identical request changes nothing and returns the same\nroutes, so a caller that lost a response can simply send it again. No\nidempotency key is required, because there is no second effect to\nsuppress.\n\nPromoting a new default demotes the old one in the same transaction, so\nno send ever observes two. **This changes which identity subscribers\nhear from next.** Bindings already authorized against the previously\ndefault connection keep their consent and stop being deliverable until\nthat connection is default again; nothing moves consent from one\nidentity to another, and nothing falls back between them.\n\nThe first connection created in an environment whose default notifier\nhas no route at all is attached by `createChannelConnection` itself, so\na first setup does not have to call this to start working. A later\nconnection never displaces an existing route on its own.\n\nRefusals reuse the closed Problem vocabulary:\n\n- the notifier or connection does not exist in this environment, or\n belongs to another tenant — `resource_not_found` 404, identically in\n both cases;\n- the connection is archived — `request_invalid` 400 with a\n `connection_id` field error, because an archived connection is\n terminal and routing to it would be silently undeliverable.\n", "tags": ["Channel connections"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["connections:write"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachNotifierConnectionRequest" }, "examples": { "attach": { "value": { "notifier_id": "default", "connection_id": "chcon_11111111111111111111111111111111", "is_default": true } } } } } }, "responses": { "200": { "description": "Every route this notifier now has, including the one just written.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotifierConnectionCollection" }, "examples": { "routes": { "value": { "items": [ { "notifier_id": "default", "connection_id": "chcon_11111111111111111111111111111111", "is_default": true }, { "notifier_id": "default", "connection_id": "chcon_22222222222222222222222222222222", "is_default": false } ], "total": 2, "page": 1, "page_size": 50 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/notifier-connections/{notifier_id}/{connection_id}": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/NotifierId" }, { "$ref": "#/components/parameters/ChannelConnectionId" } ], "delete": { "operationId": "detachNotifierConnection", "summary": "Stop routing a notifier through a connection", "description": "Removes one route. The connection itself is untouched and keeps its\nidentity, its credential custody, and every binding subscribers gave\nit — this is the reversible half of retiring an identity, and archive\nis the terminal one.\n\nDetaching the default leaves the notifier with no default, which stops\nits sends and new authorizations rather than moving them somewhere\nelse. That refusal is the point: a notifier silently failing over to\nanother identity would put a different bot in front of subscribers who\nnever consented to it.\n\nRepeat-safe. Removing a route that is already gone returns the\nnotifier's remaining routes rather than a 404, because a caller that\nlost the first response must be able to confirm the outcome.\n", "tags": ["Channel connections"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["connections:write"], "responses": { "200": { "description": "The routes this notifier has left.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotifierConnectionCollection" }, "examples": { "routes": { "value": { "items": [ { "notifier_id": "default", "connection_id": "chcon_11111111111111111111111111111111", "is_default": true }, { "notifier_id": "default", "connection_id": "chcon_22222222222222222222222222222222", "is_default": false } ], "total": 2, "page": 1, "page_size": 50 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/recipient-experience": { "parameters": [{ "$ref": "#/components/parameters/ProjectId" }], "get": { "operationId": "getProjectRecipientExperience", "summary": "Read project-owned recipient brand and fallback locale", "tags": ["Recipient experience"], "security": [ { "clerkSession": [] }, { "bearerGrant": [] }, { "bearerCredential": [] } ], "x-required-scopes": ["projects:read"], "x-organization-membership": "required", "responses": { "200": { "description": "Current constrained project recipient experience.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRecipientExperience" }, "examples": { "configured": { "value": { "project_id": "project_synthetic", "default_locale": "es", "brand": { "display_name": "Acme Alerts", "logo_asset_id": "asset_ac1e0000000000000000000000000001", "accent_color": "#4F46E5", "color_scheme": "system" }, "row_version": 2, "updated_at": "2026-08-22T18:00:00Z", "diagnostic_id": "diag_n17_project_experience" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "updateProjectRecipientExperience", "summary": "Replace project-owned recipient brand and fallback locale", "tags": ["Recipient experience"], "security": [ { "clerkSession": [] }, { "bearerGrant": [] }, { "bearerCredential": [] } ], "x-required-scopes": ["projects:write"], "x-organization-membership": "required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectRecipientExperienceRequest" }, "examples": { "configure": { "value": { "default_locale": "es", "brand": { "display_name": "Acme Alerts", "logo_asset_id": "asset_ac1e0000000000000000000000000001", "accent_color": "#4F46E5", "color_scheme": "system" }, "row_version": 1 } } } } } }, "responses": { "200": { "description": "Updated constrained project recipient experience.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRecipientExperience" } } } }, "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" } } } }, "/v1/projects/{project_id}/recipient-experience/logo": { "parameters": [{ "$ref": "#/components/parameters/ProjectId" }], "put": { "operationId": "uploadRecipientBrandLogo", "summary": "Normalize, host, and configure one project recipient logo", "description": "Accepts only a bounded PNG payload. WhooshBang decodes and re-encodes it, stores only the normalized result, and atomically replaces the project's prior logo. The service never fetches a customer URL.", "tags": ["Recipient experience"], "security": [ { "clerkSession": [] }, { "bearerGrant": [] }, { "bearerCredential": [] } ], "x-required-scopes": ["projects:write"], "x-organization-membership": "required", "parameters": [ { "name": "WhooshBang-Recipient-Experience-Version", "in": "header", "required": true, "description": "The project recipient-experience row version last observed by the owner.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "image/png": { "schema": { "type": "string", "format": "binary", "maxLength": 524288 } } } }, "responses": { "200": { "description": "Normalized asset metadata and the configuration now using it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientBrandLogoUpload" } } } }, "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" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/recipient-experience": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" } ], "get": { "operationId": "getEnvironmentRecipientExperience", "summary": "Read one environment's exact recipient browser policy", "tags": ["Recipient experience"], "security": [ { "clerkSession": [] }, { "bearerGrant": [] }, { "bearerCredential": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["projects:read"], "x-organization-membership": "required", "responses": { "200": { "description": "Current revisioned environment recipient experience.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentRecipientExperience" }, "examples": { "configured": { "value": { "project_id": "project_synthetic", "environment_id": "environment_project_synthetic_test", "environment": "test", "revision": 2, "enabled_channels": ["telegram"], "connectable_channels": ["telegram"], "allowed_origins": ["https://app.acme.example"], "return_destinations": [ { "key": "notifications", "url": "https://app.acme.example/settings/notifications" } ], "updated_at": "2026-08-22T18:00:00Z", "diagnostic_id": "diag_n17_environment_experience" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "updateEnvironmentRecipientExperience", "summary": "Replace one environment's enabled channels and exact browser policy", "description": "Origins are exact scheme/host/port values, written in any spelling that\nmeans that same origin: a trailing slash, an uppercase host, and an\nexplicitly written default port are accepted and stored in canonical\nform. Return destinations are registered developer keys resolving to\nexact URLs. Wildcards, templates, arbitrary recipient-time URLs, and\nchannels not backed by an offered compatible connection are refused.\n", "tags": ["Recipient experience"], "security": [ { "clerkSession": [] }, { "bearerGrant": [] }, { "bearerCredential": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["projects:write"], "x-organization-membership": "required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEnvironmentRecipientExperienceRequest" }, "examples": { "configure": { "value": { "revision": 1, "enabled_channels": ["telegram"], "allowed_origins": ["https://app.acme.example"], "return_destinations": [ { "key": "notifications", "url": "https://app.acme.example/settings/notifications" } ] } } } } } }, "responses": { "200": { "description": "Updated revisioned environment recipient experience.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentRecipientExperience" } } } }, "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" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/subscribers/{subscriber_id}/channel-settings": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "in": "path", "name": "subscriber_id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "get": { "operationId": "getSubscriberChannelSettings", "summary": "Read safe channel settings for one subscriber", "description": "Uses the exact authorized organization, project, environment, subscriber\nand default notifier. Only existing bindings can be managed; this never\nestablishes consent or revives a revoked binding. Dashboard mutations\nrequire current organization administrator membership. A project\ncredential must name its own stored project and environment.\n", "tags": ["Recipient experience"], "security": [ { "clerkSession": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] }, { "bearerCredential": [] } ], "x-required-scopes": ["subscriptions:read"], "responses": { "200": { "description": "Current safe subscriber channel settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriberChannelSettings" } } } }, "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" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/subscribers/{subscriber_id}/bindings/{binding_id}/{action}": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "in": "path", "name": "subscriber_id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "path", "name": "binding_id", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } }, { "in": "path", "name": "action", "required": true, "schema": { "type": "string", "enum": ["pause", "resume", "unsubscribe"] } } ], "post": { "operationId": "transitionSubscriberBinding", "summary": "Pause, resume, or unsubscribe one existing binding", "description": "Uses the exact authorized organization, project, environment, subscriber\nand default notifier. Only existing bindings can be managed; this never\nestablishes consent or revives a revoked binding. Dashboard mutations\nrequire current organization administrator membership. A project\ncredential must name its own stored project and environment.\n", "tags": ["Recipient experience"], "security": [ { "clerkSession": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] }, { "bearerCredential": [] } ], "x-required-scopes": ["subscriptions:write"], "responses": { "200": { "description": "Current safe subscriber channel settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriberChannelSettings" } } } }, "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" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/subscribers/{subscriber_id}/preferred-binding": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "in": "path", "name": "subscriber_id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "put": { "operationId": "setSubscriberPreferredBinding", "summary": "Set the preferred active binding for one subscriber", "description": "Uses the exact authorized organization, project, environment, subscriber\nand default notifier. Only existing bindings can be managed; this never\nestablishes consent or revives a revoked binding. Dashboard mutations\nrequire current organization administrator membership. A project\ncredential must name its own stored project and environment.\n", "tags": ["Recipient experience"], "security": [ { "clerkSession": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] }, { "bearerCredential": [] } ], "x-required-scopes": ["subscriptions:write"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPreferredBindingRequest" } } } }, "responses": { "200": { "description": "Current safe subscriber channel settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriberChannelSettings" } } } }, "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" } } } }, "/v1/recipient-sessions": { "post": { "operationId": "createRecipientSession", "summary": "Create one attenuated recipient browser session", "description": "The authenticated project credential supplies organization, project, and\nenvironment. The request supplies only one subscriber, optional locale,\noptional registered return key, and bounded expiry. The response is the\nonly reveal of the browser capability and contains no resolved return\nURL, provider identity, group state, or application credential.\n", "tags": ["Recipient experience"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["subscriptions:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_project_environment", "operation_id", "key"], "equivalence": "validated_request", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRecipientSessionRequest" }, "examples": { "create": { "value": { "subscriber_id": "user_123", "locale": "es", "return_to": "notifications", "expires_in_seconds": 900 } } } } } }, "responses": { "201": { "description": "Creation-only recipient capability and safe session projection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRecipientSessionResponse" }, "examples": { "created": { "value": { "session": { "id": "recipient_session_user_123", "capability_prefix": "wb_rs1.rsc_AAAAAAAAAAAAAAAAAAAAAA", "state": "active", "configuration_revision": 2, "locale": "es", "brand": { "display_name": "Acme Alerts", "logo_asset_id": "asset_ac1e0000000000000000000000000001", "accent_color": "#4F46E5", "color_scheme": "system" }, "panel_copy": {}, "channels": [ { "channel": "telegram", "state": "available", "preferred": false } ], "operations": [ "session:read", "handoff:create", "binding:pause", "binding:resume", "binding:revoke", "preference:write" ], "expires_at": "2026-08-22T18:15:00Z", "diagnostic_id": "diag_n17_recipient_session_created" }, "browser_capability": "wb_rs1.rsc_AAAAAAAAAAAAAAAAAAAAAA.BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB", "hosted_url": "https://connect.whooshbang.com/recipient-settings" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/v1/recipient-sessions/{recipient_session_id}": { "parameters": [ { "name": "recipient_session_id", "in": "path", "required": true, "description": "Opaque recipient-session identity; never browser authority.", "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } } ], "delete": { "operationId": "revokeRecipientSession", "summary": "Revoke one recipient browser session", "description": "Immediately and terminally ends the session selected inside the\nauthenticated project environment. The browser capability stops\nworking, and any independently issued provider handoff that has not\nalready been consumed stops yielding an authorization link.\n\nRepeating the request is safe. An already revoked, absent, or\nout-of-scope session produces the same empty response, so this route\ncannot be used to enumerate session identifiers across environments or\norganizations.\n", "tags": ["Recipient experience"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["subscriptions:write"], "x-repeat-semantics": { "same_target": "idempotent", "capability_returned": false }, "responses": { "204": { "description": "The session is no longer usable in this project environment." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/recipient-session": { "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Exact configured browser origin, pinned on first successful exchange.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "get": { "operationId": "getRecipientSession", "summary": "Read the current browser-safe recipient session", "tags": ["Recipient experience"], "security": [{ "recipientSessionCapability": [] }], "responses": { "200": { "description": "Safe state for this capability's one subscriber.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientSession" }, "examples": { "active": { "value": { "id": "recipient_session_user_123", "capability_prefix": "wb_rs1.rsc_AAAAAAAAAAAAAAAAAAAAAA", "state": "active", "configuration_revision": 2, "locale": "es", "brand": { "display_name": "Acme Alerts", "logo_asset_id": "asset_ac1e0000000000000000000000000001", "accent_color": "#4F46E5", "color_scheme": "system" }, "panel_copy": {}, "channels": [ { "channel": "telegram", "state": "connected", "binding_id": "binding_user_123_telegram", "preferred": true } ], "preference": { "notifier_id": "default", "binding_id": "binding_user_123_telegram", "connection_id": "connection_acme_telegram", "channel": "telegram", "row_version": 1, "updated_at": "2026-08-22T18:01:00Z", "diagnostic_id": "diag_n17_preferred_binding" }, "operations": [ "session:read", "handoff:create", "binding:pause", "binding:resume", "binding:revoke", "preference:write" ], "expires_at": "2026-08-22T18:15:00Z", "diagnostic_id": "diag_n17_recipient_session" } } } } } }, "401": { "$ref": "#/components/responses/RecipientCapabilityInvalid" }, "403": { "$ref": "#/components/responses/RecipientOriginForbidden" } } } }, "/v1/recipient-session/logo/{asset_id}": { "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Exact configured browser origin pinned to the recipient session.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } }, { "name": "asset_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/RecipientBrandAssetId" } } ], "get": { "operationId": "getRecipientBrandLogo", "summary": "Serve this session's current normalized recipient logo", "tags": ["Recipient experience"], "security": [{ "recipientSessionCapability": [] }], "responses": { "200": { "description": "Canonical PNG bytes for the exact brand projected into this session.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } } }, "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/RecipientCapabilityInvalid" }, "403": { "$ref": "#/components/responses/RecipientOriginForbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/recipient-session/handoffs": { "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "post": { "operationId": "createProviderHandoff", "summary": "Create one independently single-use hosted provider handoff", "tags": ["Recipient experience"], "security": [{ "recipientSessionCapability": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProviderHandoffRequest" }, "examples": { "popup": { "value": { "channel": "telegram", "completion": { "mode": "popup", "target_origin": "https://app.acme.example", "opener_nonce": "AAAAAAAAAAAAAAAAAAAAAA" } } } } } } }, "responses": { "201": { "description": "Exact hosted handoff and exact-origin completion contract.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderHandoff" }, "examples": { "handoff": { "value": { "id": "handoff_user_123_telegram", "channel": "telegram", "state": "pending", "handoff_url": "https://connect.whooshbang.com/handoffs/wb_rh1.rhc_AAAAAAAAAAAAAAAAAAAAAA.BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB", "completion": { "mode": "popup", "target_origin": "https://app.acme.example", "opener_nonce": "AAAAAAAAAAAAAAAAAAAAAA" }, "expires_at": "2026-08-22T18:05:00Z", "diagnostic_id": "diag_n17_provider_handoff" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/RecipientCapabilityInvalid" }, "403": { "$ref": "#/components/responses/RecipientOriginForbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/recipient-session/preference": { "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "put": { "operationId": "setPreferredBinding", "summary": "Select one exact active binding for this subscriber and notifier", "description": "The capability supplies subscriber and tenant scope. The binding must be\nactive, connection-bound, attached, enabled, and offered by that exact\nenvironment. Moving an existing preference is explicit. An unavailable\npreference later refuses direct delivery without selecting a fallback.\n", "tags": ["Recipient experience"], "security": [{ "recipientSessionCapability": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPreferredBindingRequest" }, "examples": { "prefer": { "value": { "binding_id": "binding_user_123_telegram_replacement", "row_version": 1 } } } } } }, "responses": { "200": { "description": "The exact preferred binding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferredBinding" }, "examples": { "preferred": { "value": { "notifier_id": "default", "binding_id": "binding_user_123_telegram_replacement", "connection_id": "connection_acme_telegram_replacement", "channel": "telegram", "row_version": 2, "updated_at": "2026-08-22T18:01:00Z", "diagnostic_id": "diag_n17_preferred_binding" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/RecipientCapabilityInvalid" }, "403": { "$ref": "#/components/responses/RecipientOriginForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/v1/recipient-session/bindings/{binding_id}/{action}": { "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255 } }, { "name": "binding_id", "in": "path", "required": true, "description": "Exact binding owned by this capability's subscriber; never authority by itself.", "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": ["pause", "resume", "revoke"] } } ], "post": { "operationId": "transitionBinding", "summary": "Pause, resume, or revoke this subscriber's exact binding", "tags": ["Recipient experience"], "security": [{ "recipientSessionCapability": [] }], "responses": { "200": { "description": "Refreshed safe recipient session. A preference naming a paused or revoked binding remains an unavailable exact choice, so delivery refuses without fallback until the recipient explicitly selects another active binding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientSession" } } } }, "401": { "$ref": "#/components/responses/RecipientCapabilityInvalid" }, "403": { "$ref": "#/components/responses/RecipientOriginForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/email-consent-assertions": { "post": { "operationId": "assertEmailConsent", "summary": "Assert existing consent for one customer-owned email recipient", "description": "Creates or resolves the subscriber and activates the exact binding atomically.\nShared email refuses assertions. Active domain, OAuth, webhook and connection\nauthority are required. Recipient revocation, pause, suppression and holds win.\nIdentical retries return current binding state; changed inputs conflict.\n", "tags": ["Subscribers"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["subscriptions:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_project_environment", "operation_id", "key"], "equivalence": "validated_request", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssertEmailConsentRequest" }, "examples": { "assertion": { "value": { "subscriber_id": "customer-42", "notifier_id": "updates", "connection_id": "chcon_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "domain_id": "emldom_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "address": "User@xn--bcher-kva.example", "consented": true, "consented_at": "2026-09-01T12:00:00.000Z", "source": "account-settings" } } } } } }, "responses": { "201": { "description": "The asserted binding with authenticated audit metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BindingSummary" }, "examples": { "binding": { "value": { "id": "binding_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "project_id": "proj_example", "environment": "live", "subscriber_id": "customer-42", "notifier_id": "updates", "channel": "email", "connection_id": "chcon_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "status": "active", "address": "User@xn--bcher-kva.example", "consent": { "kind": "asserted_prior_consent", "consented_at": "2026-09-01T12:00:00.000Z", "source": "account-settings", "asserted_at": "2026-09-11T12:00:00.000Z", "asserted_by": { "kind": "credential", "id": "cred_example" }, "domain_id": "emldom_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } } } } } }, "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" } } } }, "/v1/subscribers": { "post": { "operationId": "createSubscriber", "summary": "Create a subscriber and optional initial static-group memberships", "description": "Every group key must resolve to an active group in the authenticated\nproject environment. Subscriber and memberships commit together or not\nat all. A later create conflicts instead of replacing memberships.\n", "tags": ["Subscribers"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["subscriptions:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_project_environment", "operation_id", "key"], "equivalence": "validated_request", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriberRequest" }, "examples": { "initialGroups": { "value": { "subscriber_id": "user_123", "locale": "es", "groups": ["organization-updates", "trial-users"] } } } } } }, "responses": { "201": { "description": "The subscriber after atomic creation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscriber" }, "examples": { "subscriber": { "value": { "subscriber_id": "user_123", "locale": "es", "created_at": "2026-08-22T18:00:00Z", "updated_at": "2026-08-22T18:00:00Z", "diagnostic_id": "diag_n17_subscriber_created" } } } } } }, "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" } } } }, "/v1/subscribers/{subscriber_id}": { "parameters": [ { "name": "subscriber_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } } ], "get": { "operationId": "getSubscriber", "summary": "Read one subscriber in the authenticated project environment", "tags": ["Subscribers"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["subscriptions:read"], "responses": { "200": { "description": "Subscriber identity and locale, without provider or group expansion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscriber" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/recipient-groups": { "get": { "operationId": "listRecipientGroups", "summary": "List static recipient groups in the authenticated environment", "tags": ["Recipient groups"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["subscriptions:read"], "parameters": [ { "name": "after", "in": "query", "required": false, "description": "Opaque cursor from the previous static-group page.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "$ref": "#/components/parameters/PageNumber" } ], "responses": { "200": { "description": "Bounded stable page of static groups.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientGroupCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "createRecipientGroup", "summary": "Create one static recipient group with an immutable key", "tags": ["Recipient groups"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["subscriptions:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_project_environment", "operation_id", "key"], "equivalence": "validated_request", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRecipientGroupRequest" }, "examples": { "create": { "value": { "key": "trial-users", "display_name": "Trial users", "description": "Organizations currently evaluating Acme." } } } } } }, "responses": { "201": { "description": "Created static group.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientGroup" }, "examples": { "group": { "value": { "id": "group_trial_users", "project_id": "project_synthetic", "environment": "test", "key": "trial-users", "display_name": "Trial users", "description": "Organizations currently evaluating Acme.", "status": "active", "membership_revision": 1, "row_version": 1, "created_at": "2026-08-22T18:00:00Z", "updated_at": "2026-08-22T18:00:00Z", "diagnostic_id": "diag_n17_recipient_group" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/recipient-groups/{group_key}": { "parameters": [ { "name": "group_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 63, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "get": { "operationId": "getRecipientGroup", "summary": "Read one static recipient group", "tags": ["Recipient groups"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["subscriptions:read"], "responses": { "200": { "description": "Current group metadata and membership revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientGroup" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "updateRecipientGroup", "summary": "Rename or redescribe an active static group", "tags": ["Recipient groups"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["subscriptions:write"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRecipientGroupRequest" } } } }, "responses": { "200": { "description": "Updated group with its immutable key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientGroup" } } } }, "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" } } }, "delete": { "operationId": "archiveRecipientGroup", "summary": "Terminally archive a group while reserving its key and history", "tags": ["Recipient groups"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["subscriptions:write"], "responses": { "200": { "description": "Archived group; repeating the operation is safe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientGroup" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/recipient-groups/{group_key}/members": { "parameters": [ { "name": "group_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 63, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "get": { "operationId": "listRecipientGroupMembers", "summary": "List active membership generations with bounded pagination", "tags": ["Recipient groups"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["subscriptions:read"], "parameters": [ { "name": "after", "in": "query", "required": false, "description": "Opaque cursor from the previous membership page.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "$ref": "#/components/parameters/PageNumber" } ], "responses": { "200": { "description": "Active member generations at the reported group revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientGroupMembershipCollection" }, "examples": { "members": { "value": { "group_key": "trial-users", "membership_revision": 1, "items": [ { "group_id": "group_trial_users", "group_key": "trial-users", "subscriber_id": "user_123", "generation": 1, "added_revision": 1, "status": "active", "created_at": "2026-08-22T18:00:00Z", "updated_at": "2026-08-22T18:00:00Z", "diagnostic_id": "diag_n17_group_membership" } ], "page": 1, "page_size": 50, "total": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/recipient-groups/{group_key}/members/{subscriber_id}": { "parameters": [ { "name": "group_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 63, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "subscriber_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } } ], "put": { "operationId": "addRecipientGroupMember", "summary": "Idempotently add one subscriber as a new membership generation", "tags": ["Recipient groups"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["subscriptions:write"], "responses": { "200": { "description": "Existing active membership or newly created generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientGroupMembership" }, "examples": { "membership": { "value": { "group_id": "group_trial_users", "group_key": "trial-users", "subscriber_id": "user_123", "generation": 1, "added_revision": 1, "status": "active", "created_at": "2026-08-22T18:00:00Z", "updated_at": "2026-08-22T18:00:00Z", "diagnostic_id": "diag_n17_group_membership" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "delete": { "operationId": "removeRecipientGroupMember", "summary": "Idempotently remove one active membership generation", "tags": ["Recipient groups"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["subscriptions:write"], "responses": { "204": { "description": "The subscriber is absent; repeating removal is a no-op." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/recipient-groups/{group_key}/broadcasts": { "parameters": [ { "name": "group_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 63, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "post": { "operationId": "createGroupBroadcast", "summary": "Accept one durable broadcast at the group's current membership revision", "description": "Fan-out creates ordinary messages unique by broadcast, subscriber, and\nhistorical membership generation. Adds after acceptance are excluded; removal\nbefore provider attempt skips that generation; re-add creates a new\ngeneration and never revives the old broadcast audience.\n", "tags": ["Group broadcasts"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["messages:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_project_environment", "operation_id", "key"], "equivalence": "validated_request_and_group_key", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGroupBroadcastRequest" }, "examples": { "create": { "value": { "notifier_id": "default", "content": { "type": "text", "text": "Your trial ends tomorrow." }, "correlation_id": "trial-ending-2026-08-23", "metadata": { "source": "billing" } } } } } } }, "responses": { "202": { "description": "Durable broadcast acceptance and snapshotted audience revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupBroadcast" }, "examples": { "accepted": { "value": { "id": "broadcast_trial_ending", "project_id": "project_synthetic", "environment": "test", "group_id": "group_trial_users", "group_key": "trial-users", "audience_revision": 1, "status": "accepted", "aggregate": { "audience": 1, "expanded": 0, "pending": 1, "provider_accepted": 0, "delivered": 0, "skipped": 0, "failed": 0, "cancelled": 0, "expired": 0 }, "accepted_at": "2026-08-22T18:00:00Z", "updated_at": "2026-08-22T18:00:00Z", "expires_at": "2026-08-23T18:00:00Z", "diagnostic_id": "diag_n17_broadcast_accepted" } } } } } }, "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" } } } }, "/v1/group-broadcasts/{broadcast_id}": { "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } } ], "get": { "operationId": "getGroupBroadcast", "summary": "Read aggregate expansion and ordinary child-message outcomes", "tags": ["Group broadcasts"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["messages:read"], "responses": { "200": { "description": "Current aggregate projection without a second delivery state machine.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupBroadcast" }, "examples": { "complete": { "value": { "id": "broadcast_trial_ending", "project_id": "project_synthetic", "environment": "test", "group_id": "group_trial_users", "group_key": "trial-users", "audience_revision": 1, "status": "complete", "aggregate": { "audience": 1, "expanded": 1, "pending": 0, "provider_accepted": 1, "delivered": 0, "skipped": 0, "failed": 0, "cancelled": 0, "expired": 0 }, "accepted_at": "2026-08-22T18:00:00Z", "updated_at": "2026-08-22T18:01:00Z", "expires_at": "2026-08-23T18:00:00Z", "diagnostic_id": "diag_n17_broadcast_complete" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/capabilities": { "get": { "operationId": "getCapabilities", "summary": "Inspect provider-neutral capabilities", "tags": ["Capabilities"], "security": [{ "bearerCredential": [] }], "x-required-scopes": ["capabilities:read"], "responses": { "200": { "description": "Current stable capability vocabulary and active degradation.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderCapabilitiesCollection" }, "examples": { "providers": { "value": { "schema": "whooshbang.provider-capabilities-collection.v1", "providers": [ { "schema": "whooshbang.provider-capabilities.v1", "provider": "telegram", "text": { "supported": true, "maximum_bytes": 4096 }, "interaction": { "confirm": { "mode": "native" }, "select": { "mode": "native" }, "input": { "mode": "conditional", "explanation": "Available when the provider returns an exact reply context for the question; otherwise the message is delivered without the control." } }, "streaming": { "mode": "final_only" }, "edit": { "supported": false }, "receipts": { "provider_accepted": true, "delivered": false, "read": false }, "contexts": { "private_chat": { "mode": "supported" }, "thread": { "mode": "unsupported" }, "group": { "mode": "unsupported" } }, "rate_limit": { "strategy": "provider_retry_after", "explanation": "Safe provider retry timing is honoured when the provider supplies it." }, "degradation": { "active": false } }, { "schema": "whooshbang.provider-capabilities.v1", "provider": "slack", "text": { "supported": true, "maximum_bytes": 12000 }, "interaction": { "confirm": { "mode": "native" }, "select": { "mode": "native" }, "input": { "mode": "native" } }, "streaming": { "mode": "final_only" }, "edit": { "supported": false }, "receipts": { "provider_accepted": true, "delivered": false, "read": false }, "contexts": { "private_chat": { "mode": "supported" }, "thread": { "mode": "unsupported" }, "group": { "mode": "unsupported" } }, "rate_limit": { "strategy": "provider_retry_after", "explanation": "Safe provider retry timing is honoured when the provider supplies it." }, "degradation": { "active": false } }, { "schema": "whooshbang.provider-capabilities.v1", "provider": "email", "text": { "supported": true, "maximum_bytes": 100000 }, "interaction": { "confirm": { "mode": "native" }, "select": { "mode": "native" }, "input": { "mode": "native" } }, "streaming": { "mode": "final_only" }, "edit": { "supported": false }, "receipts": { "provider_accepted": true, "delivered": false, "read": false }, "contexts": { "private_chat": { "mode": "supported" }, "thread": { "mode": "unsupported" }, "group": { "mode": "unsupported" } }, "rate_limit": { "strategy": "provider_retry_after", "explanation": "Safe provider retry timing is honoured when the provider supplies it." }, "degradation": { "active": false } } ], "total": 3 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/subscription-links": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" } ], "post": { "operationId": "createSubscriptionLinkInEnvironment", "summary": "Create a subscription link in a named project environment", "description": "The environment-scoped form of `createSubscriptionLink`, for a caller\nwhose authority selects an organization rather than a project. Behavior,\nrequest, and response are identical; the path names the scope the\ncredential form takes from its bearer, and the service checks it\nagainst the granting person's membership before acting.\n", "tags": ["Subscription links"], "security": [ { "clerkSession": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["subscriptions:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_organization", "operation_id", "key"], "equivalence": "validated_request", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionLinkRequest" } } } }, "responses": { "201": { "description": "The link was created in the named environment.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionLink" }, "examples": { "pending": { "value": { "id": "slink_synthetic_001", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "customer_123", "notifier_id": "default", "channels": ["telegram"], "recipient_language": "es", "connection": { "id": "connection_synthetic_telegram_001", "mode": "whooshbang_shared", "display_name": "WhooshBang", "identity": { "handle": "WhooshBangSyntheticBot", "provider": "telegram" } }, "status": "pending", "authorization_url": "https://t.me/WhooshBangSyntheticBot?start=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "created_at": "2026-07-25T17:45:00Z", "updated_at": "2026-07-25T17:45:00Z", "expires_at": "2026-07-25T18:00:00Z", "diagnostic_id": "diag_link_pending_001" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/subscription-links/{subscription_link_id}": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/SubscriptionLinkId" } ], "get": { "operationId": "getSubscriptionLinkInEnvironment", "summary": "Inspect a subscription link in a named project environment", "description": "The environment-scoped form of `getSubscriptionLink`. A link outside the\nnamed environment is absent, exactly as it is for a credential.\n", "tags": ["Subscription links"], "security": [ { "clerkSession": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["subscriptions:read"], "responses": { "200": { "description": "Current link state and, once completed, its safe binding summary.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionLink" }, "examples": { "activated": { "value": { "id": "slink_synthetic_001", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "customer_123", "notifier_id": "default", "channels": ["telegram"], "recipient_language": "es", "connection": { "id": "connection_synthetic_telegram_001", "mode": "whooshbang_shared", "display_name": "WhooshBang", "identity": { "handle": "WhooshBangSyntheticBot", "provider": "telegram" } }, "status": "activated", "binding": { "id": "binding_synthetic_001", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "customer_123", "notifier_id": "default", "channel": "telegram", "connection_id": "connection_synthetic_telegram_001", "status": "active" }, "created_at": "2026-07-25T17:45:00Z", "updated_at": "2026-07-25T17:47:00Z", "expires_at": "2026-07-25T18:00:00Z", "diagnostic_id": "diag_link_active_001" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/messages": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" } ], "post": { "operationId": "createMessageInEnvironment", "summary": "Create an asynchronous message in a named project environment", "description": "The environment-scoped form of `createMessage`. The path names the\norganization, project, and environment the credential form takes from its\nbearer; test and live remain a property of the named environment and are\nnever selected by the request body.\n", "tags": ["Messages"], "security": [ { "clerkSession": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["messages:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_organization", "operation_id", "key"], "equivalence": "validated_request", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMessageRequest" } } } }, "responses": { "202": { "description": "The message was accepted in the named environment.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" }, "examples": { "accepted": { "value": { "id": "msg_synthetic_001", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "customer_123", "notifier_id": "default", "binding": { "id": "binding_synthetic_001", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "customer_123", "notifier_id": "default", "channel": "telegram", "status": "active" }, "delivery_target": "simulator", "state": "accepted", "accepted_at": "2026-07-25T17:45:00Z", "updated_at": "2026-07-25T17:45:00Z", "expires_at": "2026-07-26T17:45:00Z", "delivery": { "attempt_count": 0, "highest_proven_provider_state": "none", "retry_scheduled": false }, "diagnostic_id": "diag_message_accept_001", "correlation_id": "export_987", "metadata": { "job": "export_987" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/messages/{message_id}": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/MessageId" } ], "get": { "operationId": "getMessageInEnvironment", "summary": "Inspect a message in a named project environment", "description": "The environment-scoped form of `getMessage`, including the same bounded\nlong poll. Inspection acknowledges, consumes, retries, and replays\nnothing.\n", "parameters": [ { "$ref": "#/components/parameters/ResponseInspectionWait" } ], "tags": ["Messages"], "security": [ { "clerkSession": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["messages:read"], "responses": { "200": { "description": "Canonical message state at the moment the read completed.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" }, "examples": { "accepted": { "value": { "id": "msg_synthetic_001", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "customer_123", "notifier_id": "default", "binding": { "id": "binding_synthetic_001", "project_id": "project_synthetic", "environment": "test", "subscriber_id": "customer_123", "notifier_id": "default", "channel": "telegram", "status": "active" }, "delivery_target": "simulator", "state": "provider_accepted", "accepted_at": "2026-07-25T17:45:00Z", "updated_at": "2026-07-25T17:45:02Z", "expires_at": "2026-07-26T17:45:00Z", "delivery": { "attempt_count": 1, "highest_proven_provider_state": "provider_accepted", "retry_scheduled": false }, "diagnostic_id": "diag_message_provider_001", "correlation_id": "export_987", "metadata": { "job": "export_987" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/interactions/{interaction_id}": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/InteractionId" } ], "get": { "operationId": "getInteractionInEnvironment", "summary": "Inspect an interaction response in a named project environment", "description": "The environment-scoped form of `getInteraction`, including the same\nbounded long poll and the same retained-answer semantics.\n", "parameters": [ { "$ref": "#/components/parameters/ResponseInspectionWait" } ], "tags": ["Messages"], "security": [ { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["messages:read"], "responses": { "200": { "description": "Canonical interaction state at the moment the read completed.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InteractionSummary" }, "examples": { "answered": { "value": { "id": "interaction_synthetic_confirm", "type": "confirm", "state": "answered", "expires_at": "2026-07-25T18:00:00Z", "correlation_id": "request_confirm_001", "answered_at": "2026-07-25T17:47:00Z", "answer_retained": true, "answer": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/machine-clients": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" } ], "post": { "operationId": "createMachineClientInEnvironment", "summary": "Create a destination-bound machine client in a named project environment", "description": "The environment-scoped form of `createMachineClient`. Scope remains the\nexact bound destination; the path only names where the client is created.\n", "tags": ["Machine clients"], "security": [ { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["machine-clients:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_organization", "operation_id", "key"], "equivalence": "validated_request", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMachineClientRequest" } } } }, "responses": { "201": { "description": "The machine client was created in the named environment.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineClient" }, "examples": { "provisioning": { "value": { "id": "machine_client_synthetic_001", "project_id": "project_synthetic", "environment": "test", "machine_id": "machine_synthetic_a", "notifier_id": "default", "subscriber_id": "agent_relay_operator", "binding_id": "binding_synthetic_relay", "display_name": "Synthetic local machine", "status": "provisioning", "scope_summary": [ "machine-messages:write", "machine-messages:read", "machine-events:read", "machine-events:ack" ], "created_at": "2026-07-25T17:40:00Z", "updated_at": "2026-07-25T17:40:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/machine-clients/{machine_client_id}/credentials": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "$ref": "#/components/parameters/MachineClientId" } ], "post": { "operationId": "registerMachineCredentialInEnvironment", "summary": "Register a machine-credential digest in a named project environment", "description": "The environment-scoped form of `registerMachineCredential`. Registers\nonly the credential ID and SHA-256 digest; the path only names where the\nowning machine client lives. Request and response shapes are that\noperation's exactly, including its published examples.\n", "tags": ["Machine clients"], "security": [ { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["machine-clients:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_environment", "operation_id", "key"], "equivalence": "validated_request_after_documented_defaults", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterMachineCredentialRequest" } } } }, "responses": { "200": { "description": "Existing safe credential metadata on an equivalent registration replay; never secret or digest.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineCredential" } } } }, "201": { "description": "Newly registered safe credential metadata; never secret or digest.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineCredential" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/capabilities": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" } ], "get": { "operationId": "getCapabilitiesInEnvironment", "summary": "Inspect provider-neutral capabilities for a named project environment", "description": "The environment-scoped form of `getCapabilities`. The vocabulary is\nprovider-neutral and identical; the path names the environment whose\nactive degradation is reported.\n", "tags": ["Capabilities"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["capabilities:read"], "responses": { "200": { "description": "Current stable capability vocabulary and active degradation.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderCapabilitiesCollection" }, "examples": { "providers": { "value": { "schema": "whooshbang.provider-capabilities-collection.v1", "providers": [ { "schema": "whooshbang.provider-capabilities.v1", "provider": "telegram", "text": { "supported": true, "maximum_bytes": 4096 }, "interaction": { "confirm": { "mode": "native" }, "select": { "mode": "native" }, "input": { "mode": "conditional", "explanation": "Available when the provider returns an exact reply context for the question; otherwise the message is delivered without the control." } }, "streaming": { "mode": "final_only" }, "edit": { "supported": false }, "receipts": { "provider_accepted": true, "delivered": false, "read": false }, "contexts": { "private_chat": { "mode": "supported" }, "thread": { "mode": "unsupported" }, "group": { "mode": "unsupported" } }, "rate_limit": { "strategy": "provider_retry_after", "explanation": "Safe provider retry timing is honoured when the provider supplies it." }, "degradation": { "active": false } }, { "schema": "whooshbang.provider-capabilities.v1", "provider": "slack", "text": { "supported": true, "maximum_bytes": 12000 }, "interaction": { "confirm": { "mode": "native" }, "select": { "mode": "native" }, "input": { "mode": "native" } }, "streaming": { "mode": "final_only" }, "edit": { "supported": false }, "receipts": { "provider_accepted": true, "delivered": false, "read": false }, "contexts": { "private_chat": { "mode": "supported" }, "thread": { "mode": "unsupported" }, "group": { "mode": "unsupported" } }, "rate_limit": { "strategy": "provider_retry_after", "explanation": "Safe provider retry timing is honoured when the provider supplies it." }, "degradation": { "active": false } }, { "schema": "whooshbang.provider-capabilities.v1", "provider": "email", "text": { "supported": true, "maximum_bytes": 100000 }, "interaction": { "confirm": { "mode": "native" }, "select": { "mode": "native" }, "input": { "mode": "native" } }, "streaming": { "mode": "final_only" }, "edit": { "supported": false }, "receipts": { "provider_accepted": true, "delivered": false, "read": false }, "contexts": { "private_chat": { "mode": "supported" }, "thread": { "mode": "unsupported" }, "group": { "mode": "unsupported" } }, "rate_limit": { "strategy": "provider_retry_after", "explanation": "Safe provider retry timing is honoured when the provider supplies it." }, "degradation": { "active": false } } ], "total": 3 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/email-consent-assertions": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" } ], "post": { "operationId": "assertEmailConsentInEnvironment", "summary": "Assert existing consent for one customer-owned email recipient", "description": "Creates or resolves the subscriber and activates the exact binding atomically.\nShared email refuses assertions. Active domain, OAuth, webhook and connection\nauthority are required. Recipient revocation, pause, suppression and holds win.\nIdentical retries return current binding state; changed inputs conflict.\n", "tags": ["Subscribers"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["subscriptions:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_project_environment", "operation_id", "key"], "equivalence": "validated_request", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssertEmailConsentRequest" }, "examples": { "assertion": { "value": { "subscriber_id": "customer-42", "notifier_id": "updates", "connection_id": "chcon_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "domain_id": "emldom_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "address": "User@xn--bcher-kva.example", "consented": true, "consented_at": "2026-09-01T12:00:00.000Z", "source": "account-settings" } } } } } }, "responses": { "201": { "description": "The asserted binding with authenticated audit metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BindingSummary" }, "examples": { "binding": { "value": { "id": "binding_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "project_id": "proj_example", "environment": "live", "subscriber_id": "customer-42", "notifier_id": "updates", "channel": "email", "connection_id": "chcon_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "status": "active", "address": "User@xn--bcher-kva.example", "consent": { "kind": "asserted_prior_consent", "consented_at": "2026-09-01T12:00:00.000Z", "source": "account-settings", "asserted_at": "2026-09-11T12:00:00.000Z", "asserted_by": { "kind": "credential", "id": "cred_example" }, "domain_id": "emldom_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } } } } } }, "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" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/subscribers": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" } ], "post": { "operationId": "createSubscriberInEnvironment", "summary": "Create a subscriber and initial memberships in a named project environment", "description": "The environment-scoped form of `createSubscriber`, for a caller whose\nauthority selects an organization rather than a project. Behavior, request,\nand response are identical; the path names the scope the credential\nform takes from its bearer, and the service checks it against the\npresenting session or grant before acting.\n", "tags": ["Subscribers"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["subscriptions:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_project_environment", "operation_id", "key"], "equivalence": "validated_request", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriberRequest" }, "examples": { "initialGroups": { "value": { "subscriber_id": "user_123", "locale": "es", "groups": ["organization-updates", "trial-users"] } } } } } }, "responses": { "201": { "description": "The subscriber after atomic creation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscriber" }, "examples": { "subscriber": { "value": { "subscriber_id": "user_123", "locale": "es", "created_at": "2026-08-22T18:00:00Z", "updated_at": "2026-08-22T18:00:00Z", "diagnostic_id": "diag_n17_subscriber_created" } } } } } }, "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" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/subscribers/{subscriber_id}": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "name": "subscriber_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } } ], "get": { "operationId": "getSubscriberInEnvironment", "summary": "Read one subscriber in a named project environment", "description": "The environment-scoped form of `getSubscriber`. A subscriber outside the\nnamed environment is absent, exactly as it is for a credential.\n", "tags": ["Subscribers"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["subscriptions:read"], "responses": { "200": { "description": "Subscriber identity and locale, without provider or group expansion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscriber" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/subscribers/{subscriber_id}": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "name": "subscriber_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } } ], "delete": { "operationId": "eraseSubscriber", "summary": "Erase one subscriber across the project", "description": "Erases the person represented by this customer-supplied subscriber id\nacross both project environments. Personal content, answers, identities,\nand identifiers are removed while non-identifying delivery and usage\nshells remain. Pending work and old capabilities cannot restore or send\ndata for the erased person.\n\nRepeating the operation is safe, including when the subscriber is already\nabsent. Project-environment credentials cannot call this project-wide\noperation. A provider action that has already begun returns\n`privacy_operation_in_progress` rather than claiming erasure won the race;\nretry after that operation finishes.\n", "tags": ["Subscribers"], "security": [ { "clerkSession": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": [ "subscriptions:write", "messages:write", "machine-clients:write" ], "x-organization-membership": "required", "x-repeat-semantics": { "same_target": "idempotent", "secret_returned": false }, "responses": { "204": { "description": "The subscriber's personal data is erased or was already absent." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/projects/{project_id}/subscribers/{subscriber_id}/data-export": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "name": "subscriber_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } } ], "get": { "operationId": "getSubscriberDataExport", "summary": "Export all customer-controlled data held for one subscriber", "description": "Returns one complete, machine-readable artifact across every environment\nin the project. `provided_by_subscriber` is the Article 20 portable subset;\nthe three provenance sections together provide the Article 15 access copy.\nWhooshBang-controller audit and service log data is identified as excluded\nand requires a separate recipient request. Project-environment credentials\ncannot call this project-wide operation.\n", "tags": ["Subscribers"], "security": [ { "clerkSession": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": [ "subscriptions:read", "messages:read", "machine-clients:read" ], "x-organization-membership": "required", "responses": { "200": { "description": "Complete project-wide customer-controller subscriber data export.", "headers": { "Content-Disposition": { "schema": { "type": "string" }, "description": "Fixed safe attachment filename." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriberDataExport" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/recipient-groups": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" } ], "get": { "operationId": "listRecipientGroupsInEnvironment", "summary": "List static recipient groups in a named project environment", "description": "The environment-scoped form of `listRecipientGroups`. The page, its\nbounds, and its cursor are identical; the path names the environment\nwhose groups are listed.\n", "tags": ["Recipient groups"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["subscriptions:read"], "parameters": [ { "name": "after", "in": "query", "required": false, "description": "Opaque cursor from the previous static-group page.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "$ref": "#/components/parameters/PageNumber" } ], "responses": { "200": { "description": "Bounded stable page of static groups.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientGroupCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "createRecipientGroupInEnvironment", "summary": "Create one static recipient group in a named project environment", "description": "The environment-scoped form of `createRecipientGroup`. The key is\nimmutable and unique inside the named environment, exactly as it is for\na credential.\n", "tags": ["Recipient groups"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["subscriptions:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_project_environment", "operation_id", "key"], "equivalence": "validated_request", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRecipientGroupRequest" }, "examples": { "create": { "value": { "key": "trial-users", "display_name": "Trial users", "description": "Organizations currently evaluating Acme." } } } } } }, "responses": { "201": { "description": "Created static group.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientGroup" }, "examples": { "group": { "value": { "id": "group_trial_users", "project_id": "project_synthetic", "environment": "test", "key": "trial-users", "display_name": "Trial users", "description": "Organizations currently evaluating Acme.", "status": "active", "membership_revision": 1, "row_version": 1, "created_at": "2026-08-22T18:00:00Z", "updated_at": "2026-08-22T18:00:00Z", "diagnostic_id": "diag_n17_recipient_group" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/recipient-groups/{group_key}": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "name": "group_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 63, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "get": { "operationId": "getRecipientGroupInEnvironment", "summary": "Read one static recipient group in a named project environment", "description": "The environment-scoped form of `getRecipientGroup`. A group outside the\nnamed environment is absent, exactly as it is for a credential.\n", "tags": ["Recipient groups"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["subscriptions:read"], "responses": { "200": { "description": "Current group metadata and membership revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientGroup" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "updateRecipientGroupInEnvironment", "summary": "Rename or redescribe an active static group in a named project environment", "description": "The environment-scoped form of `updateRecipientGroup`. The key stays\nimmutable and the row version still guards the write.\n", "tags": ["Recipient groups"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["subscriptions:write"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRecipientGroupRequest" } } } }, "responses": { "200": { "description": "Updated group with its immutable key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientGroup" } } } }, "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" } } }, "delete": { "operationId": "archiveRecipientGroupInEnvironment", "summary": "Terminally archive a group in a named project environment", "description": "The environment-scoped form of `archiveRecipientGroup`. The key stays\nreserved, accepted broadcasts and membership provenance are preserved,\nand repeating the operation is safe.\n", "tags": ["Recipient groups"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["subscriptions:write"], "responses": { "200": { "description": "Archived group; repeating the operation is safe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientGroup" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/recipient-groups/{group_key}/members": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "name": "group_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 63, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "get": { "operationId": "listRecipientGroupMembersInEnvironment", "summary": "List active membership generations in a named project environment", "description": "The environment-scoped form of `listRecipientGroupMembers`. Removed\ngenerations stay internal here too; only current active members are\npublished.\n", "tags": ["Recipient groups"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["subscriptions:read"], "parameters": [ { "name": "after", "in": "query", "required": false, "description": "Opaque cursor from the previous membership page.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "$ref": "#/components/parameters/PageNumber" } ], "responses": { "200": { "description": "Active member generations at the reported group revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientGroupMembershipCollection" }, "examples": { "members": { "value": { "group_key": "trial-users", "membership_revision": 1, "items": [ { "group_id": "group_trial_users", "group_key": "trial-users", "subscriber_id": "user_123", "generation": 1, "added_revision": 1, "status": "active", "created_at": "2026-08-22T18:00:00Z", "updated_at": "2026-08-22T18:00:00Z", "diagnostic_id": "diag_n17_group_membership" } ], "page": 1, "page_size": 50, "total": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/recipient-groups/{group_key}/members/{subscriber_id}": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "name": "group_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 63, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "subscriber_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } } ], "put": { "operationId": "addRecipientGroupMemberInEnvironment", "summary": "Idempotently add one subscriber in a named project environment", "description": "The environment-scoped form of `addRecipientGroupMember`. A subscriber\nthat does not already exist in the named environment is absent; this\noperation creates memberships, never subscribers.\n", "tags": ["Recipient groups"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["subscriptions:write"], "responses": { "200": { "description": "Existing active membership or newly created generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientGroupMembership" }, "examples": { "membership": { "value": { "group_id": "group_trial_users", "group_key": "trial-users", "subscriber_id": "user_123", "generation": 1, "added_revision": 1, "status": "active", "created_at": "2026-08-22T18:00:00Z", "updated_at": "2026-08-22T18:00:00Z", "diagnostic_id": "diag_n17_group_membership" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "delete": { "operationId": "removeRecipientGroupMemberInEnvironment", "summary": "Idempotently remove one active membership in a named project environment", "description": "The environment-scoped form of `removeRecipientGroupMember`. Removal\nstops not-yet-attempted broadcast children and is a no-op for a\nsubscriber that is already absent.\n", "tags": ["Recipient groups"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["subscriptions:write"], "responses": { "204": { "description": "The subscriber is absent; repeating removal is a no-op." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/recipient-groups/{group_key}/broadcasts": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "name": "group_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 63, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "post": { "operationId": "createGroupBroadcastInEnvironment", "summary": "Accept one durable broadcast in a named project environment", "description": "The environment-scoped form of `createGroupBroadcast`. Fan-out,\naudience snapshotting, and child-message uniqueness are identical; test\nand live remain a property of the named environment and are never\nselected by the request body.\n", "tags": ["Group broadcasts"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["messages:write"], "x-idempotency": { "required": true, "retention_seconds": 604800, "scope": ["authenticated_project_environment", "operation_id", "key"], "equivalence": "validated_request_and_group_key", "replay_retention_extends": false }, "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGroupBroadcastRequest" }, "examples": { "create": { "value": { "notifier_id": "default", "content": { "type": "text", "text": "Your trial ends tomorrow." }, "correlation_id": "trial-ending-2026-08-23", "metadata": { "source": "billing" } } } } } } }, "responses": { "202": { "description": "Durable broadcast acceptance and snapshotted audience revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupBroadcast" }, "examples": { "accepted": { "value": { "id": "broadcast_trial_ending", "project_id": "project_synthetic", "environment": "test", "group_id": "group_trial_users", "group_key": "trial-users", "audience_revision": 1, "status": "accepted", "aggregate": { "audience": 1, "expanded": 0, "pending": 1, "provider_accepted": 0, "delivered": 0, "skipped": 0, "failed": 0, "cancelled": 0, "expired": 0 }, "accepted_at": "2026-08-22T18:00:00Z", "updated_at": "2026-08-22T18:00:00Z", "expires_at": "2026-08-23T18:00:00Z", "diagnostic_id": "diag_n17_broadcast_accepted" } } } } } }, "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" } } } }, "/v1/projects/{project_id}/environments/{environment_id}/group-broadcasts/{broadcast_id}": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/EnvironmentId" }, { "name": "broadcast_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } } ], "get": { "operationId": "getGroupBroadcastInEnvironment", "summary": "Read aggregate expansion and child outcomes in a named project environment", "description": "The environment-scoped form of `getGroupBroadcast`. The aggregate is the\nsame projection over expansion and ordinary child message states; a\nbroadcast outside the named environment is absent.\n", "tags": ["Group broadcasts"], "security": [ { "clerkSession": [] }, { "bearerCredential": [] }, { "bearerGrant": [] }, { "bearerOrganizationCredential": [] } ], "x-required-scopes": ["messages:read"], "responses": { "200": { "description": "Current aggregate projection without a second delivery state machine.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupBroadcast" }, "examples": { "complete": { "value": { "id": "broadcast_trial_ending", "project_id": "project_synthetic", "environment": "test", "group_id": "group_trial_users", "group_key": "trial-users", "audience_revision": 1, "status": "complete", "aggregate": { "audience": 1, "expanded": 1, "pending": 0, "provider_accepted": 1, "delivered": 0, "skipped": 0, "failed": 0, "cancelled": 0, "expired": 0 }, "accepted_at": "2026-08-22T18:00:00Z", "updated_at": "2026-08-22T18:01:00Z", "expires_at": "2026-08-23T18:00:00Z", "diagnostic_id": "diag_n17_broadcast_complete" } } } } } }, "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 ` 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": 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.", "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } }, "ApiCredentialId": { "name": "credential_id", "in": "path", "required": true, "description": "Canonical opaque project credential identity; never a readable secret.", "schema": { "$ref": "#/components/schemas/ApiCredentialId" } }, "OrganizationCredentialId": { "name": "organization_credential_id", "in": "path", "required": true, "description": "Canonical opaque organization credential identity; never a readable secret.", "schema": { "$ref": "#/components/schemas/OrganizationCredentialId" } }, "ApiCredentialAfterCursor": { "name": "after", "in": "query", "required": false, "description": "Opaque cursor returned by the previous credential page.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" } }, "ApiCredentialPageLimit": { "name": "limit", "in": "query", "required": false, "description": "Maximum credential metadata records returned in one page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "ListAfterCursor": { "name": "after", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page of this list.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" } }, "ListPageLimit": { "name": "limit", "in": "query", "required": false, "description": "Maximum records returned in one page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "PageNumber": { "name": "page", "in": "query", "required": false, "description": "1-based page number, for a caller showing a person where they are in a\nlist rather than walking the whole set. Mutually exclusive with\n`after`: sending both is `request_invalid`, because a cursor and a page\nnumber are two different answers to \"which records next\". A page past\nthe end of the list is an empty page, not an error.\n\nWhat is bounded is the row the page starts at, not the page number.\n`(page - 1) * limit` may not exceed 50,000 — the deepest row any\npublished list ceiling reaches — and a request past that is\n`request_invalid`. So every row of every list stays addressable\nwhatever page size the caller chose.\n", "schema": { "$ref": "#/components/schemas/ListPageNumber" } }, "ProjectAfterCursor": { "name": "after", "in": "query", "required": false, "description": "Opaque cursor returned by the previous project page.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" } }, "ProjectPageLimit": { "name": "limit", "in": "query", "required": false, "description": "Maximum projects returned in one page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "MessageId": { "name": "message_id", "in": "path", "required": true, "description": "Opaque logical message identity; never authorization.", "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } }, "NotificationImageAssetId": { "name": "asset_id", "in": "path", "required": true, "description": "Opaque immutable notification-image version identity; never authorization.", "schema": { "$ref": "#/components/schemas/NotificationImageAssetId" } }, "InteractionId": { "name": "interaction_id", "in": "path", "required": true, "description": "Opaque interaction identity; never authorization.", "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } }, "MachineClientId": { "name": "machine_client_id", "in": "path", "required": true, "description": "Opaque machine-client identity; never authorization.", "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } }, "MachineCredentialId": { "name": "credential_id", "in": "path", "required": true, "description": "Canonical opaque credential identifier; never a readable secret.", "schema": { "$ref": "#/components/schemas/MachineCredentialId" } }, "MachineEventId": { "name": "event_id", "in": "path", "required": true, "description": "Opaque event identity constrained to the authenticated machine stream.", "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } }, "ChannelConnectionId": { "name": "connection_id", "in": "path", "required": true, "description": "Opaque connection identity; never authorization.", "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } }, "ConnectionTestId": { "name": "test_id", "in": "path", "required": true, "description": "Opaque identity of one owner-triggered connection test; never authorization.", "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } }, "NotifierId": { "name": "notifier_id", "in": "path", "required": true, "description": "The notifier whose routing is being changed, as `default_notifier.id` on the project environment reports it. This is the notifier's own identity, not the `notifier_id` reference a send carries.", "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } }, "CustomerEndpointId": { "name": "endpoint_id", "in": "path", "required": true, "description": "Opaque endpoint identity; never authorization and never a URL.", "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" } }, "MachineAfterCursor": { "name": "after", "in": "query", "required": false, "description": "Exact atomically committed cursor returned by the previous successful\npoll or acknowledgement. Omit only for the first poll. A foreign,\nunknown, or known-but-uncommitted cursor fails closed and cannot rewind\nthe stream.\n", "schema": { "$ref": "#/components/schemas/MachineCursor" } }, "MachinePollWait": { "name": "wait", "in": "query", "required": false, "description": "Bounded server hold time in seconds.", "schema": { "type": "integer", "minimum": 0, "maximum": 30, "default": 30 } }, "ResponseInspectionWait": { "name": "wait", "in": "query", "required": false, "description": "Bounded server hold time in whole seconds. Omission defaults to 30;\nzero requests an immediate read. A wait that expires returns the\ncurrent resource successfully rather than a timeout problem.\n", "schema": { "type": "integer", "minimum": 0, "maximum": 30, "default": 30 } }, "MachinePollLimit": { "name": "limit", "in": "query", "required": false, "description": "Maximum stable-ordered events returned.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } } }, "headers": { "DiagnosticId": { "description": "Safe public correlation identifier for protected diagnostics.", "schema": { "$ref": "#/components/schemas/DiagnosticId" } } }, "schemas": { "OpaqueIdentifier": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\u0000-\u001f-Ÿ

]+$", "description": "An opaque identifier. Its shape, ordering, and embedded content are not public promises." }, "ListPageNumber": { "type": "integer", "minimum": 1, "maximum": 50000, "description": "A 1-based page number. Present on a response only when the request addressed the list by page rather than by cursor: a cursor walk cannot know which page it is on. What is bounded is the row a page starts at, not the page number: a request whose first row would be past 50,000 — the deepest row any published list ceiling reaches — is refused as `request_invalid`. Bounding the page number instead would make the last rows of a large list unreachable at a small page size, which is exactly when a person is paging through one." }, "ChannelConnectionProvider": { "type": "string", "enum": ["telegram", "slack", "email"], "description": "A provider that can back a Channel Connection. A member can be frozen before its adapter exists; deployments advertise only providers they can execute." }, "ChannelConnectionMode": { "type": "string", "enum": [ "whooshbang_shared", "whooshbang_hosted", "customer_managed", "customer_byok" ], "description": "How this environment obtained its provider identity. `whooshbang_shared` selects a disclosed global WhooshBang identity; `whooshbang_hosted` authorizes the WhooshBang-owned distributed app at one provider authority without making that installation caller-selectable; the customer modes end with an identity the customer owns." }, "ChannelConnectionStatus": { "type": "string", "enum": ["pending", "active", "degraded", "disabled", "archived"], "description": "`degraded` still delivers: the identity a subscriber consented to has not changed, only its last health check. `archived` is terminal, so consent granted against it is never revived." }, "ProviderHealthState": { "type": "string", "enum": ["unknown", "healthy", "degraded", "unhealthy"] }, "ConnectionLifecycleOperation": { "type": "string", "enum": [ "validate", "provision", "reauthorize", "repair", "health", "rotate", "disable", "deprovision", "purge" ] }, "SharedProviderIdentity": { "type": "object", "description": "A WhooshBang-owned identity an environment may select. Its credential is operated by WhooshBang and is structurally absent from this API.", "required": ["id", "display_name", "health"], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "health": { "$ref": "#/components/schemas/ProviderHealthState" } }, "additionalProperties": false }, "ConnectionProvider": { "description": "What one provider supports for connection setup and lifecycle. Known provider arms forbid contradictory setup modes; deployments still omit an arm entirely until they can execute it.", "oneOf": [ { "type": "object", "required": [ "provider", "display_name", "setup_modes", "lifecycle_operations", "shared_installation_supported", "shared_identities" ], "properties": { "provider": { "const": "telegram" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "setup_modes": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "enum": [ "whooshbang_shared", "customer_managed", "customer_byok" ] } }, "lifecycle_operations": { "type": "array", "maxItems": 9, "uniqueItems": true, "items": { "$ref": "#/components/schemas/ConnectionLifecycleOperation" } }, "shared_installation_supported": { "type": "boolean" }, "shared_identities": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/SharedProviderIdentity" } } }, "additionalProperties": false }, { "type": "object", "required": [ "provider", "display_name", "setup_modes", "lifecycle_operations", "shared_installation_supported", "shared_identities" ], "properties": { "provider": { "const": "slack" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "setup_modes": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "enum": ["whooshbang_hosted", "customer_managed"] } }, "lifecycle_operations": { "type": "array", "maxItems": 9, "uniqueItems": true, "items": { "$ref": "#/components/schemas/ConnectionLifecycleOperation" } }, "shared_installation_supported": { "const": true }, "shared_identities": { "type": "array", "maxItems": 0 } }, "additionalProperties": false }, { "type": "object", "description": "The frozen email setup modes. A deployment omits this arm until an executable email adapter is registered.", "required": [ "provider", "display_name", "setup_modes", "lifecycle_operations", "shared_installation_supported", "shared_identities" ], "properties": { "provider": { "const": "email" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "setup_modes": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "enum": ["whooshbang_shared", "customer_managed"] } }, "lifecycle_operations": { "type": "array", "maxItems": 9, "uniqueItems": true, "items": { "$ref": "#/components/schemas/ConnectionLifecycleOperation" } }, "shared_installation_supported": { "const": true }, "shared_identities": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/SharedProviderIdentity" } } }, "additionalProperties": false } ] }, "ConnectionProviderCollection": { "type": "object", "required": ["items"], "properties": { "items": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/ConnectionProvider" } }, "total": { "$ref": "#/components/schemas/ListTotal" } }, "additionalProperties": false }, "ChannelConnection": { "description": "One environment's provider-discriminated connection. Credentials and provider-native authority identifiers are structurally absent.", "oneOf": [ { "$ref": "#/components/schemas/TelegramChannelConnection" }, { "$ref": "#/components/schemas/HostedChannelConnection" }, { "$ref": "#/components/schemas/CustomerApplicationChannelConnection" }, { "$ref": "#/components/schemas/EmailChannelConnection" } ] }, "ChannelConnectionCollection": { "type": "object", "required": ["items"], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/ChannelConnection" } }, "next_cursor": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" }, "page": { "$ref": "#/components/schemas/ListPageNumber" }, "page_size": { "$ref": "#/components/schemas/ListPageSize" }, "total": { "$ref": "#/components/schemas/ListTotal" } }, "additionalProperties": false }, "CreateChannelConnectionRequest": { "description": "Selects the provider identity this environment will send through, discriminated on `mode`, and naming the provider it is for. The two customer-owned modes differ only in where the bot comes from: `customer_byok` connects one the customer already has, and `customer_managed` has Telegram create a new one on the administrator's own Telegram account. Neither supersedes the other, because a bot that already exists can never be adopted into managed mode — the manager that may act for a bot is fixed when the bot is created.", "oneOf": [ { "type": "object", "description": "Reuses a disclosed WhooshBang-owned identity. WhooshBang operates its credential, so selecting one conveys no ability to read, rotate, or retire it.", "required": ["mode", "display_name", "shared_identity_id"], "properties": { "mode": { "type": "string", "enum": ["whooshbang_shared"] }, "provider": { "type": "string", "const": "telegram", "default": "telegram", "description": "This established setup arm is Telegram-only. Omitted means telegram. A provider whose setup is structurally different — an OAuth install rather than a credential — has its own arm of this union rather than bending this one." }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "shared_identity_id": { "$ref": "#/components/schemas/OpaqueIdentifier" } }, "additionalProperties": false }, { "type": "object", "description": "Connects a provider identity the customer already owns by supplying its credential.\n\nThis arm carries no identity field, and the absence is deliberate. `provider_identity_digest` is unique across every tenant, so an endpoint that digested a client-supplied identity would answer \"already claimed\" for a bot the caller does not own — an oracle for whether any given bot is connected to WhooshBang by anyone. The identity is derived server-side from a provider-validated `getMe` on the submitted credential, which no caller can forge without holding the credential itself.", "required": ["mode", "display_name", "credential"], "properties": { "mode": { "type": "string", "enum": ["customer_byok"] }, "provider": { "type": "string", "const": "telegram", "default": "telegram", "description": "This established setup arm is Telegram-only. Omitted means telegram. A provider whose setup is structurally different — an OAuth install rather than a credential — has its own arm of this union rather than bending this one." }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "credential": { "type": "string", "minLength": 1, "maxLength": 512, "writeOnly": true, "description": "The customer's own provider credential; for Telegram, the bot token BotFather issued. Write-only: it is sealed on arrival and is never echoed here or by any later read, and no reference to it appears in `ChannelConnection`." }, "confirm_webhook_takeover": { "type": "boolean", "description": "Consent to replace a webhook the identity already has. Absent or `false`, an occupied identity is refused rather than silently detaching whatever was receiving its updates." } }, "additionalProperties": false }, { "type": "object", "description": "Starts a guided setup in which Telegram creates a brand new bot on the administrator's own Telegram account. The connection comes back `pending` with a `setup` describing the one thing a human still has to do, because creating a bot is a person-only action no API of ours can perform for them.\n\nThis arm carries no credential field at all, and that absence is the entire point of the mode: Telegram hands the new bot's token to WhooshBang server to server, so it never passes through a browser, a clipboard, this request, or any response. There is nothing here for a caller to paste, and therefore nothing for a caller to leak.", "required": ["mode", "display_name", "suggested_bot_username"], "properties": { "mode": { "type": "string", "enum": ["customer_managed"] }, "provider": { "type": "string", "const": "telegram", "default": "telegram", "description": "This established setup arm is Telegram-only. Omitted means telegram. A provider whose setup is structurally different — an OAuth install rather than a credential — has its own arm of this union rather than bending this one." }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "suggested_bot_username": { "$ref": "#/components/schemas/SuggestedBotUsername" }, "suggested_bot_name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The display name prefilled in the same dialog — what a subscriber reads at the top of the chat, as opposed to the @username they address. Unlike the username this one can be changed afterwards, so it is a convenience rather than a commitment. Omit it and Telegram's dialog opens with no name suggested." } }, "additionalProperties": false }, { "type": "object", "description": "Starts a guided setup in which the customer creates and owns their own application at the provider. The connection comes back `pending` with an `app_setup` carrying the provider's own creation link, already filled in with this application's configuration where the provider allows it.\n\nThis arm carries no credential field, because at this point no credential exists: the provider issues the application's secrets when the owner creates it. They arrive later through the write-only rotation boundary, and the installation grant never arrives from the caller at all — WhooshBang obtains it from the provider's installation exchange. The three names here are what the owner's own recipients will see, which is why the caller chooses them rather than WhooshBang: a generated name would permanently brand a customer's own application with ours, and that is the one thing customer-owned modes exist to prevent.\n\nA provider that does not set a connection up this way refuses the request as an unavailable setup mode. Each provider may also refuse a name its own rules do not allow, within the bounds stated here.", "required": [ "mode", "provider", "display_name", "app_name", "bot_display_name", "app_description" ], "properties": { "mode": { "type": "string", "const": "customer_managed" }, "provider": { "$ref": "#/components/schemas/ChannelConnectionProvider" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "What this connection is called inside WhooshBang. Unrelated to what the provider shows recipients." }, "app_name": { "type": "string", "minLength": 1, "maxLength": 35, "description": "The application name the provider's creation flow is prefilled with. The owner can still change it at the provider; this is a suggestion, not a reservation." }, "bot_display_name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The bot display name in the same flow — what a recipient reads at the top of the conversation." }, "app_description": { "type": "string", "minLength": 1, "maxLength": 140, "description": "The short description the provider shows beside the application." } }, "additionalProperties": false }, { "type": "object", "description": "Starts the hosted authorization for a WhooshBang-owned distributed application installed independently at the provider authority the provider derives during authorization. The caller supplies neither installation identity nor credential material. A provider without a hosted application refuses the request as an unavailable setup mode.", "required": ["mode", "provider", "display_name"], "properties": { "mode": { "type": "string", "const": "whooshbang_hosted" }, "provider": { "$ref": "#/components/schemas/ChannelConnectionProvider" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "additionalProperties": false }, { "type": "object", "description": "Selects the recipient-verified shared email identity. No sender domain, provider installation or credential is caller supplied.", "required": [ "mode", "provider", "display_name", "shared_identity_id" ], "properties": { "mode": { "const": "whooshbang_shared" }, "provider": { "const": "email" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "shared_identity_id": { "$ref": "#/components/schemas/OpaqueIdentifier" } }, "additionalProperties": false }, { "type": "object", "description": "Authorizes one account-owned email domain to this environment connection. The installation and domain are WhooshBang ids resolved under the authenticated organization; provider team ids, API keys and OAuth credentials are forbidden by shape.", "required": [ "mode", "provider", "display_name", "installation_id", "domain_id", "sender_local_part", "sender_display_name" ], "properties": { "mode": { "const": "customer_managed" }, "provider": { "const": "email" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "installation_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "domain_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "sender_local_part": { "$ref": "#/components/schemas/EmailLocalPart" }, "sender_display_name": { "$ref": "#/components/schemas/EmailDisplayName" } }, "additionalProperties": false } ] }, "UpdateChannelConnectionRequest": { "type": "object", "description": "Edits a connection under the row version that was read. Provider, mode, identity, and ownership are immutable; replacing any of them is a new connection.", "required": ["row_version"], "properties": { "row_version": { "type": "integer", "minimum": 1 }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "status": { "type": "string", "enum": ["active", "disabled"] } }, "additionalProperties": false }, "RotateChannelConnectionCredentialRequest": { "description": "Replaces the secret behind a connection, discriminated by where a replacement can come from at all. A customer-owned bot has one only its owner can produce and therefore sends it; a managed bot has one only Telegram can issue and therefore sends nothing. An application the customer owns has separate authorities and names each one it hands over. Either way the connection keeps its provider identity, so a subscriber stays bound to the identity it consented to and only the secret changes.\n\nThe first submission during setup uses this same boundary. Handing a secret over and replacing it are the same operation — a write that never reads the old value back — and giving initial setup its own endpoint would have meant two ways to do one thing, differing only in what the connection's status happened to be.", "oneOf": [ { "type": "object", "description": "Supplies or replaces the application-specific authorities of an application the customer owns. Every authority that provider's application takes is sent together, both for the first submission during setup and for every later replacement.\n\nSending only the one that changed would read as the kinder API, and it is the wrong shape: the authorities are sealed as one versioned set, so replacing one alone would mean decrypting the others and writing them back — reading secrets at a boundary whose whole purpose is that nothing reads them.\n\n`application_identity` is safe metadata; the secrets are write-only and are never readable afterwards by any surface. `ingress_secret` is optional in shape because not every provider signs inbound requests with a secret the owner holds; a provider whose application does have one refuses a request that leaves it out, and refuses an `application_identity` that is not in its own format.\n\nThere is no bot-token field here, and the absence is the point: WhooshBang obtains the installation grant from the provider's installation exchange, so it never passes through a browser, a clipboard, this request, or any response.", "required": [ "provider", "application_identity", "application_secret" ], "properties": { "provider": { "$ref": "#/components/schemas/ChannelConnectionProvider" }, "application_identity": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7e]+$", "description": "The identifier the provider issued for the application — for Slack, its Client ID. Safe application metadata rather than an authority: it identifies the application in an authorization redirect the provider's users can already see." }, "application_secret": { "type": "string", "minLength": 1, "maxLength": 512, "writeOnly": true, "description": "The secret the application authenticates to the provider with — for Slack, its Client Secret. Write-only: sealed on arrival, never echoed here or by any later read, and reachable only by the exchanges that need it." }, "ingress_secret": { "type": "string", "minLength": 1, "maxLength": 512, "writeOnly": true, "description": "The secret that verifies an inbound request really came from the provider — for Slack, its Signing Secret. Write-only on the same terms, and reachable only by ingress verification." } }, "additionalProperties": false }, { "type": "object", "description": "Replaces the customer-owned credential behind a connection. The connection keeps its provider identity, so a subscriber stays bound to the identity it consented to and only the secret changes; a credential for a different identity is refused.", "required": ["credential"], "properties": { "credential": { "type": "string", "minLength": 1, "maxLength": 512, "writeOnly": true, "description": "The replacement provider credential. Write-only on the same terms as the credential a `customer_byok` create supplies: sealed on arrival and never echoed." } }, "additionalProperties": false }, { "type": "object", "description": "Rotates a `customer_managed` connection, whose replacement only Telegram can issue. Asked to rotate, Telegram revokes the bot's current token and returns the successor to the manager that created it, so there is no customer-supplied credential to send and no field here to send one in — a caller able to supply one would be describing a bot this mode never handed it. The identity is untouched: the same bot keeps the same @username and the same subscribers, and only the secret behind it is new.", "required": ["source"], "properties": { "source": { "type": "string", "const": "provider_managed", "description": "Names the provider as the origin of the replacement. It is stated rather than inferred so that a body which lost its credential in transit is refused as malformed instead of being read as a request to have the provider mint a new token." } }, "additionalProperties": false } ] }, "ConnectionTestKind": { "type": "string", "enum": ["outbound_notification", "signed_interaction"], "description": "Which half of a connection a test exercises. `outbound_notification` proves this exact identity can put a message in front of the person who set it up. `signed_interaction` proves the opposite direction: that the provider can reach this deployment's interactivity URL and that the request it signs verifies against the secret we hold. The two fail for entirely different reasons, so they are never collapsed into one result.", "$comment": "Provider-neutral vocabulary. Slack is the only provider that implements either today; a provider that cannot run one refuses it rather than reporting a pass it never proved." }, "ConnectionTestRecoveryAction": { "type": "string", "enum": [ "none", "complete_setup", "replace_credentials", "reinstall", "retry_later", "check_request_url", "contact_support" ], "description": "The exact safe next action for one test result, in product vocabulary.\n\nIt is a different vocabulary from a connection's own recovery action because the actions genuinely differ: a test that nothing answered is fixed by checking the request URL the provider was given, and a request that arrived and did not verify is fixed by re-entering the app's secrets — neither of which is a lifecycle transition on the connection.\n\n`check_request_url` is also the honest answer when nobody simply pressed the button: the window closed with nothing arriving, and that has exactly two causes." }, "ConnectionTestStatus": { "type": "string", "enum": ["pending", "succeeded", "failed", "expired"], "description": "`pending` means the test is placed and its answer has not arrived; a signed-interaction test stays there until somebody presses the button it sent. `expired` is the honest reading of a pending test whose window closed: nothing failed, nobody answered." }, "ConnectionTestFailureCode": { "type": "string", "enum": [ "setup_incomplete", "verification_target_unknown", "credential_unavailable", "provider_rejected", "provider_unavailable", "provider_rate_limited", "unverified_request_received" ], "description": "Why a test did not pass, in a vocabulary the owner can act on rather than the provider's wire error.\n\n`verification_target_unknown` means nobody has installed the app from this deployment yet, so there is no owner to send a test to. `unverified_request_received` is a statement of fact and not a diagnosis: a request carrying this test's own challenge reached the interactivity URL and its signature did not verify against the secret this connection holds.\n\nA window that closed with nothing arriving is not in this list, because it is not a failure: it reads as `expired`, which says nobody answered rather than that anything broke." }, "ConnectionTestEvidence": { "type": "object", "description": "What a finished test actually observed. Every field is safe to render, log, and paste into an issue: no credential, no provider-native app, workspace, channel, or user identifier, and no message content.", "properties": { "identity_handle": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The visible handle the test went out as — the same identity a subscriber would see." }, "workspace_display_name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The provider workspace the test ran in, as its own members see it named." }, "accepted_at": { "$ref": "#/components/schemas/Timestamp", "description": "When the provider accepted the outbound message. Acceptance is the provider's own answer, not our belief." }, "observed_at": { "$ref": "#/components/schemas/Timestamp", "description": "When the signed request the test was waiting for arrived and verified." }, "round_trip_ms": { "type": "integer", "minimum": 0, "maximum": 86400000, "description": "Milliseconds from placing the test to observing its answer." }, "signature_verified": { "type": "boolean", "description": "Whether the provider's signature over the untouched request body verified against the secret this connection custodies. Present only once a request has arrived." }, "ingress_host": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The public host the provider actually called, which is what a misconfigured or stale request URL gets wrong. It is this deployment's own hostname and names no tenant." } }, "additionalProperties": false }, "ConnectionTest": { "type": "object", "description": "One owner-triggered proof that an exact connection still works, run on demand and answered with evidence rather than with a claim.\n\nIt is deliberately incapable of carrying a secret: nothing here is a credential, a provider-native identifier, or message content, and a test that failed says why in a closed vocabulary rather than by quoting a provider.", "required": [ "id", "connection_id", "kind", "status", "requested_at", "expires_at", "recovery_action", "diagnostic_id" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "connection_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "kind": { "$ref": "#/components/schemas/ConnectionTestKind" }, "status": { "$ref": "#/components/schemas/ConnectionTestStatus" }, "requested_at": { "$ref": "#/components/schemas/Timestamp" }, "completed_at": { "$ref": "#/components/schemas/Timestamp", "description": "When the test settled. Absent while it is still pending." }, "expires_at": { "$ref": "#/components/schemas/Timestamp", "description": "When a pending test stops waiting. A test that reaches this without an answer becomes `expired`, which is not a failure of the connection." }, "evidence": { "$ref": "#/components/schemas/ConnectionTestEvidence" }, "failure_code": { "$ref": "#/components/schemas/ConnectionTestFailureCode" }, "recovery_action": { "$ref": "#/components/schemas/ConnectionTestRecoveryAction", "description": "The exact safe next action for this result. `none` on a pass." }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" } }, "additionalProperties": false }, "ConnectionTestCollection": { "type": "object", "description": "This connection's recent tests, newest first. It is the audit-safe failure history for a connection: what was tried, when, and what came back.", "required": ["items"], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/ConnectionTest" } }, "next_cursor": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" }, "page": { "$ref": "#/components/schemas/ListPageNumber" }, "page_size": { "$ref": "#/components/schemas/ListPageSize" }, "total": { "$ref": "#/components/schemas/ListTotal" } }, "additionalProperties": false }, "CreateConnectionTestRequest": { "type": "object", "description": "Places one test against an exact connection. It carries nothing but which test to run: a test needs no target, because the only person it may address is the one who installed the app.", "required": ["kind"], "properties": { "kind": { "$ref": "#/components/schemas/ConnectionTestKind" } }, "additionalProperties": false }, "CustomerApplicationManifest": { "type": "object", "description": "The exact configuration an application the customer creates and owns is created from, as data rather than as a URL-encoded blob.\n\nIt exists so the owner can read what they are about to approve, and so a reviewer can check it, without opening the provider. It is built by the provider that owns the format, so `manifest` is that provider's own document and `provider` says whose. It carries configuration only: no organization, project, or environment, no credential, and no provider-native identifier. Any opaque handle inside the request URLs selects candidate setup state and authorizes nothing — a request still has to carry the provider's own proof over the untouched body before anything inside it is believed.", "required": [ "provider", "creation_url", "app_name", "bot_display_name", "description", "bot_scopes", "user_scopes", "request_urls", "diagnostic_id" ], "properties": { "provider": { "$ref": "#/components/schemas/ChannelConnectionProvider" }, "creation_url": { "type": "string", "format": "uri", "pattern": "^https://[^\\s]+$", "maxLength": 8192, "description": "The same prefilled creation link the setup carries, repeated here so one read answers both questions." }, "app_name": { "type": "string", "minLength": 1, "maxLength": 35 }, "bot_display_name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "minLength": 1, "maxLength": 140 }, "bot_scopes": { "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Every provider scope or permission the application's bot will ask for, exactly as the provider will show them. Raw provider vocabulary on purpose: this is the screen the owner is about to approve, and translating it would make it unverifiable." }, "user_scopes": { "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Every provider scope a recipient will be asked for when they sign in. Separate from the bot scopes because they are approved by different people at different moments. Empty for a provider whose recipients never sign in through the application." }, "request_urls": { "type": "object", "description": "Where this deployment answers the application. Each is present only when the provider calls it separately: a provider that delivers events and interactions to one endpoint names it once, and one with no recipient sign-in has no recipient redirect. A stale or edited value here is the failure a signed-interaction test detects.", "minProperties": 1, "properties": { "events": { "type": "string", "format": "uri", "pattern": "^https://[^\\s]+$", "maxLength": 2048 }, "interactions": { "type": "string", "format": "uri", "pattern": "^https://[^\\s]+$", "maxLength": 2048 }, "installation_redirect": { "type": "string", "format": "uri", "pattern": "^https://[^\\s]+$", "maxLength": 2048 }, "recipient_redirect": { "type": "string", "format": "uri", "pattern": "^https://[^\\s]+$", "maxLength": 2048 } }, "additionalProperties": false }, "manifest": { "type": "object", "description": "The literal configuration document the provider is handed, in that provider's own format, for a provider that creates an application from one. Reproduced whole so what the owner reviews and what the provider receives cannot drift apart. Absent for a provider whose application is configured field by field rather than from a document.", "additionalProperties": true }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" } }, "additionalProperties": false }, "NotifierConnectionRoute": { "type": "object", "description": "One notifier's use of one connection in the same environment. This is the record that decides which identity a send actually leaves through: a connection nothing routes to is configured and inert, and a subscriber cannot authorize against it either. Routing is deliberately separate from creating the connection so that adding a second identity never moves traffic on its own.", "required": ["notifier_id", "connection_id", "is_default"], "properties": { "notifier_id": { "$ref": "#/components/schemas/OpaqueIdentifier", "description": "The notifier's own identity, as `default_notifier.id` reports it on the project environment. Deliberately not the `notifier_id` reference a send carries: a send names a notifier by a stable public reference, and routing names the exact row, so renaming a reference cannot silently repoint traffic." }, "connection_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "is_default": { "type": "boolean", "description": "Whether this is the one connection the notifier sends and authorizes through. A notifier has at most one default at a time; the mapping is plural so later routing rules have somewhere to live, but exactly one route decides today's traffic. A notifier whose routes are all non-default sends nothing." } }, "additionalProperties": false }, "NotifierConnectionCollection": { "type": "object", "description": "The routes read back after a change, or every route in the environment when listed. Ordered by notifier and then connection so a caller diffing two reads sees a real change rather than a reordering.", "required": ["items"], "properties": { "items": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/NotifierConnectionRoute" } }, "next_cursor": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" }, "page": { "$ref": "#/components/schemas/ListPageNumber" }, "page_size": { "$ref": "#/components/schemas/ListPageSize" }, "total": { "$ref": "#/components/schemas/ListTotal" } }, "additionalProperties": false }, "AttachNotifierConnectionRequest": { "type": "object", "description": "Routes a notifier through a connection in the same environment, and optionally makes it the default. Repeating an identical request changes nothing, so a caller that lost a response can simply send it again.\n\nPromoting a new default demotes the old one in the same transaction, so no send ever sees two. That is a real change to which identity subscribers hear from next: bindings already authorized against the previous connection keep their consent and stop being deliverable until that connection is default again. Consent is never moved between identities.", "required": ["notifier_id", "connection_id"], "properties": { "notifier_id": { "$ref": "#/components/schemas/OpaqueIdentifier", "description": "The notifier's own identity, as `default_notifier.id` reports it on the project environment." }, "connection_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "is_default": { "type": "boolean", "default": true, "description": "Defaults to true because attaching a connection a notifier will not use is rarely the intent, and the plural mapping exists for routing rules that do not exist yet. Send `false` to record the route without moving traffic to it." } }, "additionalProperties": false }, "DiagnosticId": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$", "description": "A safe public identifier used to correlate protected service diagnostics." }, "IdempotencyKey": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[!-~]+$", "description": "Visible ASCII, scoped by authenticated environment, operation ID, and key, and retained for seven days from first acceptance." }, "OrganizationProjection": { "type": "object", "description": "The current Clerk organization projected as a WhooshBang tenant. Clerk organization and user identifiers are not public fields.", "required": [ "id", "name", "status", "membership", "created_at", "updated_at", "diagnostic_id" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "status": { "type": "string", "enum": ["active", "suspended"] }, "membership": { "$ref": "#/components/schemas/OrganizationMembershipSummary" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" } }, "additionalProperties": false }, "UpdateProjectRequest": { "type": "object", "description": "Sets the project privacy policy. Moving from standard to minimal erases stored identifying profile data; moving to private also erases recipient language. Increasing collection does not restore erased data.", "required": ["privacy_mode"], "properties": { "privacy_mode": { "$ref": "#/components/schemas/PrivacyMode" } }, "additionalProperties": false }, "PrivacyMode": { "type": "string", "enum": ["minimal", "standard", "private"], "description": "Project profile collection policy. minimal (the default for new and existing projects) keeps recipient language only; standard permits messenger profile data; private retains delivery routing and the customer-supplied subscriber identifier, with no profile data. Lowering collection erases existing fields the new mode disallows." }, "CreateProjectRequest": { "type": "object", "description": "Creates one project inside the organization selected by the authenticated human session.", "required": ["name", "slug"], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "slug": { "type": "string", "minLength": 1, "maxLength": 63, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "default_locale": { "$ref": "#/components/schemas/RecipientLanguage", "default": "en", "description": "The application fallback locale for recipient-owned surfaces when no session, subscriber, or supported provider locale is available." }, "privacy_mode": { "$ref": "#/components/schemas/PrivacyMode", "default": "minimal" } }, "additionalProperties": false }, "DefaultNotifierSummary": { "type": "object", "description": "The default notifier created transactionally with one project environment.", "required": [ "id", "environment_id", "display_name", "status", "is_default" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "display_name": { "const": "Default" }, "status": { "type": "string", "enum": ["active", "disabled"] }, "is_default": { "const": true } }, "additionalProperties": false }, "ProjectEnvironment": { "type": "object", "description": "A test or live project environment with its transactionally created default notifier.", "required": ["id", "project_id", "kind", "status", "default_notifier"], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "kind": { "$ref": "#/components/schemas/Environment" }, "status": { "type": "string", "enum": ["active", "disabled"] }, "default_notifier": { "$ref": "#/components/schemas/DefaultNotifierSummary" } }, "additionalProperties": false }, "Project": { "type": "object", "description": "An organization-scoped application project with its complete test/live bootstrap.", "required": [ "id", "organization_id", "name", "slug", "status", "default_locale", "environments", "created_at", "updated_at", "diagnostic_id", "privacy_mode" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "organization_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "slug": { "type": "string", "minLength": 1, "maxLength": 63, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "status": { "type": "string", "enum": ["active", "disabled"] }, "default_locale": { "$ref": "#/components/schemas/RecipientLanguage" }, "environments": { "type": "array", "minItems": 2, "maxItems": 2, "x-unique-property": "kind", "items": { "$ref": "#/components/schemas/ProjectEnvironment" } }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" }, "privacy_mode": { "$ref": "#/components/schemas/PrivacyMode" } }, "additionalProperties": false }, "ProjectCollection": { "type": "object", "description": "A stable page of projects inside the authenticated organization.", "required": ["items"], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Project" } }, "next_cursor": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" }, "page": { "$ref": "#/components/schemas/ListPageNumber" }, "page_size": { "$ref": "#/components/schemas/ListPageSize" }, "total": { "$ref": "#/components/schemas/ListTotal" } }, "additionalProperties": false }, "RecipientLanguage": { "type": "string", "enum": [ "en", "es", "pt-BR", "fr", "de", "it", "nl", "pl", "ru", "uk", "tr", "id", "ar", "fa", "hi", "zh-Hans" ], "description": "A supported canonical recipient language tag." }, "RecipientCopyKey": { "type": "string", "enum": [ "hostedConsent.openProvider", "hostedConsent.readyDetail", "hostedConsent.readyTitle", "hostedConsent.returnToApplication", "consent.accept", "consent.deny", "consent.prompt", "management.heading", "management.next", "management.pause", "management.previous", "management.resume", "panel.heading", "panel.empty", "panel.connect", "panel.connected", "panel.handoffCancelled", "panel.loading", "panel.prefer", "panel.preferenceMoved", "panel.preferred", "panel.waiting" ], "description": "A deliberately allowlisted customer-voiced recipient-copy field. System refusals, status, failure, and mandatory stop guidance are not addressable." }, "RecipientCopyOverride": { "type": "object", "description": "One sparse project + language + string override. Omitted keys continue to use the complete shipped catalog.", "required": [ "project_id", "language", "key", "value", "created_at", "updated_at" ], "properties": { "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "language": { "$ref": "#/components/schemas/RecipientLanguage" }, "key": { "$ref": "#/components/schemas/RecipientCopyKey" }, "value": { "$ref": "#/components/schemas/RecipientCopyOverrideValue" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" } }, "additionalProperties": false }, "RecipientCopyOverrideCollection": { "type": "object", "description": "All sparse recipient-copy overrides for one project, optionally filtered to one canonical language, plus the exact safe address and length metadata integrations need to edit them.", "required": [ "customizable_keys", "items", "maximum_length_by_key", "supported_languages" ], "properties": { "customizable_keys": { "type": "array", "description": "Every customer-voiced string address accepted by the update endpoint. System-owned strings are absent.", "minItems": 22, "maxItems": 22, "uniqueItems": true, "items": { "$ref": "#/components/schemas/RecipientCopyKey" } }, "items": { "type": "array", "maxItems": 352, "items": { "$ref": "#/components/schemas/RecipientCopyOverride" } }, "maximum_length_by_key": { "type": "object", "description": "The exact Unicode code-point ceiling for each customizable string address.", "required": [ "hostedConsent.openProvider", "hostedConsent.readyDetail", "hostedConsent.readyTitle", "hostedConsent.returnToApplication", "consent.accept", "consent.deny", "consent.prompt", "management.heading", "management.next", "management.pause", "management.previous", "management.resume", "panel.heading", "panel.empty", "panel.connect", "panel.connected", "panel.handoffCancelled", "panel.loading", "panel.prefer", "panel.preferenceMoved", "panel.preferred", "panel.waiting" ], "properties": { "hostedConsent.openProvider": { "type": "integer", "const": 80 }, "hostedConsent.readyDetail": { "type": "integer", "const": 500 }, "hostedConsent.readyTitle": { "type": "integer", "const": 500 }, "hostedConsent.returnToApplication": { "type": "integer", "const": 80 }, "consent.accept": { "type": "integer", "const": 40 }, "consent.deny": { "type": "integer", "const": 40 }, "consent.prompt": { "type": "integer", "const": 500 }, "management.heading": { "type": "integer", "const": 500 }, "management.next": { "type": "integer", "const": 40 }, "management.pause": { "type": "integer", "const": 40 }, "management.previous": { "type": "integer", "const": 40 }, "management.resume": { "type": "integer", "const": 40 }, "panel.heading": { "type": "integer", "const": 80 }, "panel.empty": { "type": "integer", "const": 500 }, "panel.connect": { "type": "integer", "const": 40 }, "panel.connected": { "type": "integer", "const": 40 }, "panel.handoffCancelled": { "type": "integer", "const": 500 }, "panel.loading": { "type": "integer", "const": 500 }, "panel.prefer": { "type": "integer", "const": 40 }, "panel.preferenceMoved": { "type": "integer", "const": 500 }, "panel.preferred": { "type": "integer", "const": 40 }, "panel.waiting": { "type": "integer", "const": 500 } }, "additionalProperties": false }, "supported_languages": { "type": "array", "description": "Every canonical recipient language independently addressable by the update endpoint.", "minItems": 16, "maxItems": 16, "uniqueItems": true, "items": { "$ref": "#/components/schemas/RecipientLanguage" } }, "next_cursor": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" }, "page": { "$ref": "#/components/schemas/ListPageNumber" }, "page_size": { "$ref": "#/components/schemas/ListPageSize" }, "total": { "$ref": "#/components/schemas/ListTotal" } }, "additionalProperties": false }, "UpdateRecipientCopyOverrideRequest": { "type": "object", "description": "Sets one exact project + language + string value. Delete the same address to restore the shipped default.", "required": ["value"], "properties": { "value": { "$ref": "#/components/schemas/RecipientCopyOverrideValue" } }, "additionalProperties": false, "x-max-json-bytes": 2048 }, "CreateApiCredentialRequest": { "type": "object", "description": "Creates one credential inside the project environment selected by the authenticated administration path.", "required": ["label", "scopes"], "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "scopes": { "$ref": "#/components/schemas/ApiCredentialScopeSet" } }, "additionalProperties": false }, "CreateOrganizationCredentialRequest": { "type": "object", "description": "Creates one credential against the whole organization rather than one project environment.", "required": ["label", "scopes"], "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "scopes": { "$ref": "#/components/schemas/OrganizationCredentialScopeSet" } }, "additionalProperties": false }, "RotateOrganizationCredentialRequest": { "type": "object", "description": "Creates a replacement with the same label and scopes and schedules terminal revocation of the replaced credential after the declared overlap.", "required": ["overlap_seconds"], "properties": { "overlap_seconds": { "type": "integer", "minimum": 0, "maximum": 86400 } }, "additionalProperties": false }, "OrganizationCredentialId": { "type": "string", "pattern": "^ocred_[A-Za-z0-9_-]{21}[AQgw]$", "description": "ocred_ followed by the canonical unpadded base64url encoding of exactly 16 random bytes." }, "OrganizationCredential": { "type": "object", "description": "Safe organization-scoped API credential metadata. It carries no project or environment, because it names neither: a request does, in its path. It never contains a bearer secret, digest, Clerk identifier, or digest-key reference.", "required": [ "id", "prefix", "label", "scopes", "created_by", "created_at", "status" ], "properties": { "id": { "$ref": "#/components/schemas/OrganizationCredentialId" }, "prefix": { "$ref": "#/components/schemas/OrganizationCredentialPrefix" }, "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "scopes": { "$ref": "#/components/schemas/OrganizationCredentialScopeSet" }, "created_by": { "$ref": "#/components/schemas/OpaqueIdentifier", "description": "An opaque WhooshBang member identifier. It is never a Clerk user identifier." }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "last_used_at": { "$ref": "#/components/schemas/Timestamp" }, "scheduled_revocation_at": { "$ref": "#/components/schemas/Timestamp", "description": "When an active credential in a rotation overlap becomes terminally revoked." }, "status": { "type": "string", "enum": ["active", "revoked"] }, "revoked_at": { "$ref": "#/components/schemas/Timestamp" } }, "allOf": [ { "if": { "properties": { "status": { "const": "revoked" } }, "required": ["status"] }, "then": { "required": ["revoked_at"], "properties": { "revoked_at": {}, "scheduled_revocation_at": false } }, "else": { "properties": { "revoked_at": false } } } ], "additionalProperties": false }, "OrganizationCredentialCollection": { "type": "object", "description": "A stable page of safe organization-credential metadata for one organization.", "required": ["items"], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/OrganizationCredential" } }, "next_cursor": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" }, "page": { "$ref": "#/components/schemas/ListPageNumber" }, "page_size": { "$ref": "#/components/schemas/ListPageSize" }, "total": { "$ref": "#/components/schemas/ListTotal" } }, "additionalProperties": false }, "OrganizationCredentialSecretReveal": { "type": "object", "description": "The creation-only response. The secret is emitted in this response exactly once and is never available from list, rotate-target, revoke, or later read responses.", "required": ["credential", "secret"], "properties": { "credential": { "$ref": "#/components/schemas/OrganizationCredential" }, "secret": { "$ref": "#/components/schemas/OrganizationCredentialSecret" } }, "additionalProperties": false }, "OrganizationCredentialRotation": { "type": "object", "description": "A creation-only replacement secret plus safe metadata for the credential it replaces.", "required": ["credential", "replaced_credential"], "properties": { "credential": { "$ref": "#/components/schemas/OrganizationCredentialSecretReveal" }, "replaced_credential": { "$ref": "#/components/schemas/OrganizationCredential" } }, "additionalProperties": false }, "RotateApiCredentialRequest": { "type": "object", "description": "Creates a replacement with the same label and scopes and schedules terminal revocation of the replaced credential after the declared overlap.", "required": ["overlap_seconds"], "properties": { "overlap_seconds": { "type": "integer", "minimum": 0, "maximum": 86400 } }, "additionalProperties": false }, "ApiCredentialId": { "type": "string", "pattern": "^pcred_[A-Za-z0-9_-]{21}[AQgw]$", "description": "pcred_ followed by the canonical unpadded base64url encoding of exactly 16 random bytes." }, "ApiCredential": { "type": "object", "description": "Safe environment-scoped API credential metadata. It never contains a bearer secret, digest, Clerk identifier, or digest-key reference.", "required": [ "id", "project_id", "environment_id", "environment", "prefix", "label", "scopes", "created_by", "created_at", "status" ], "properties": { "id": { "$ref": "#/components/schemas/ApiCredentialId" }, "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment": { "$ref": "#/components/schemas/Environment" }, "prefix": { "$ref": "#/components/schemas/ApiCredentialPrefix" }, "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "scopes": { "$ref": "#/components/schemas/ApiCredentialScopeSet" }, "created_by": { "$ref": "#/components/schemas/OpaqueIdentifier", "description": "An opaque WhooshBang member identifier. It is never a Clerk user identifier." }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "last_used_at": { "$ref": "#/components/schemas/Timestamp" }, "scheduled_revocation_at": { "$ref": "#/components/schemas/Timestamp", "description": "When an active credential in a rotation overlap becomes terminally revoked." }, "status": { "type": "string", "enum": ["active", "revoked"] }, "revoked_at": { "$ref": "#/components/schemas/Timestamp" } }, "allOf": [ { "if": { "properties": { "status": { "const": "revoked" } }, "required": ["status"] }, "then": { "required": ["revoked_at"], "properties": { "revoked_at": {}, "scheduled_revocation_at": false } }, "else": { "properties": { "revoked_at": false } } } ], "additionalProperties": false }, "ApiCredentialCollection": { "type": "object", "description": "A stable page of safe credential metadata in one project environment.", "required": ["items"], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/ApiCredential" } }, "next_cursor": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" }, "page": { "$ref": "#/components/schemas/ListPageNumber" }, "page_size": { "$ref": "#/components/schemas/ListPageSize" }, "total": { "$ref": "#/components/schemas/ListTotal" } }, "additionalProperties": false }, "ApiCredentialSecretReveal": { "type": "object", "description": "The creation-only response. The secret is emitted in this response exactly once and is never available from list, rotate-target, revoke, or later read responses.", "required": ["credential", "secret"], "properties": { "credential": { "$ref": "#/components/schemas/ApiCredential" }, "secret": { "$ref": "#/components/schemas/ApiCredentialSecret" } }, "additionalProperties": false }, "ApiCredentialRotation": { "type": "object", "description": "A creation-only replacement secret plus safe metadata for the credential it replaces.", "required": ["credential", "replaced_credential"], "properties": { "credential": { "$ref": "#/components/schemas/ApiCredentialSecretReveal" }, "replaced_credential": { "$ref": "#/components/schemas/ApiCredential" } }, "additionalProperties": false }, "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"], "properties": { "url": { "type": "string", "format": "uri", "minLength": 8, "maxLength": 2048, "pattern": "^https://[^\\s]+$" }, "event_types": { "type": "array", "minItems": 1, "maxItems": 11, "uniqueItems": true, "items": { "$ref": "#/components/schemas/CustomerEventType" } }, "local_test": { "type": "boolean", "default": false, "description": "Explicit local-tooling marker. Production deployments reject true even though local test tooling accepts loopback HTTP before persistence." } }, "additionalProperties": false }, "RotateCustomerEndpointRequest": { "type": "object", "required": ["overlap_seconds"], "properties": { "overlap_seconds": { "type": "integer", "minimum": 60, "maximum": 86400 } }, "additionalProperties": false }, "CustomerEndpoint": { "type": "object", "description": "Safe endpoint lifecycle and health metadata. URL, signing material, event bodies, answers, and response bodies are structurally absent.", "required": [ "id", "project_id", "environment_id", "environment", "status", "verification_status", "event_types", "secret_version", "health", "created_at", "updated_at", "diagnostic_id" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment": { "$ref": "#/components/schemas/Environment" }, "status": { "$ref": "#/components/schemas/CustomerEndpointStatus" }, "verification_status": { "type": "string", "enum": ["pending", "failed", "verified"] }, "event_types": { "type": "array", "minItems": 1, "maxItems": 11, "uniqueItems": true, "items": { "$ref": "#/components/schemas/CustomerEventType" } }, "secret_version": { "type": "integer", "minimum": 1 }, "health": { "type": "string", "enum": ["never_delivered", "healthy", "failing"] }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "verification_attempted_at": { "$ref": "#/components/schemas/Timestamp" }, "verified_at": { "$ref": "#/components/schemas/Timestamp" }, "rotated_at": { "$ref": "#/components/schemas/Timestamp" }, "paused_at": { "$ref": "#/components/schemas/Timestamp" }, "disabled_at": { "$ref": "#/components/schemas/Timestamp" }, "last_success_at": { "$ref": "#/components/schemas/Timestamp" }, "last_failure": { "$ref": "#/components/schemas/CustomerEndpointFailure" }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" } }, "additionalProperties": false }, "CustomerEndpointCollection": { "type": "object", "required": ["items"], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/CustomerEndpoint" } }, "next_cursor": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" }, "page": { "$ref": "#/components/schemas/ListPageNumber" }, "page_size": { "$ref": "#/components/schemas/ListPageSize" }, "total": { "$ref": "#/components/schemas/ListTotal" } }, "additionalProperties": false }, "CustomerEndpointMutationResult": { "type": "object", "required": ["endpoint"], "properties": { "endpoint": { "$ref": "#/components/schemas/CustomerEndpoint" }, "secret": { "$ref": "#/components/schemas/CustomerEndpointSecret" } }, "additionalProperties": false, "description": "The initial create/rotate result includes secret. An equivalent idempotent replay returns the same logical endpoint without revealing the secret again." }, "CustomerEndpointAttemptCollection": { "type": "object", "required": ["endpoint_id", "attempts"], "properties": { "endpoint_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "attempts": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/CustomerEndpointAttemptDiagnostic" } }, "next_cursor": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" }, "page": { "$ref": "#/components/schemas/ListPageNumber" }, "page_size": { "$ref": "#/components/schemas/ListPageSize" }, "total": { "$ref": "#/components/schemas/ListTotal" } }, "additionalProperties": false }, "CustomerEndpointVerificationChallenge": { "type": "object", "required": ["schema", "endpoint_id", "challenge"], "properties": { "schema": { "const": "whooshbang.endpoint-verification.v1" }, "endpoint_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "challenge": { "type": "string", "pattern": "^[A-Za-z0-9+/]{43}=$" } }, "additionalProperties": false, "description": "Exact signed request bytes. A verifier echoes these exact bytes with valid webhook headers to prove it possesses the endpoint secret." }, "BindingSummary": { "description": "A safe channel binding identity. Raw Telegram chat and user identifiers are never exposed. An email address is optional and appears only when the organization supplied it under asserted prior consent; shared recipient-observed addresses remain private. Legacy bindings may omit connection_id because no exact connection was recorded when they were authorized.", "oneOf": [ { "type": "object", "required": [ "id", "project_id", "environment", "subscriber_id", "notifier_id", "channel", "status" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment": { "$ref": "#/components/schemas/Environment" }, "subscriber_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "notifier_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "channel": { "enum": ["telegram", "slack"] }, "connection_id": { "$ref": "#/components/schemas/OpaqueIdentifier", "description": "The exact channel connection this binding was authorized through. Absent only on legacy bindings that predate channel connections." }, "status": { "enum": ["active", "paused", "revoked"] } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "project_id", "environment", "subscriber_id", "notifier_id", "channel", "connection_id", "status", "consent" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment": { "$ref": "#/components/schemas/Environment" }, "subscriber_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "notifier_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "channel": { "const": "email" }, "connection_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "status": { "enum": ["active", "paused", "revoked"] }, "consent": { "type": "object", "required": ["kind", "observed_at"], "properties": { "kind": { "const": "recipient_observed" }, "observed_at": { "$ref": "#/components/schemas/Timestamp" } }, "additionalProperties": false }, "masked_address": { "type": "string", "minLength": 3, "maxLength": 254, "description": "Masked recipient address. Never the full mailbox." } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "project_id", "environment", "subscriber_id", "notifier_id", "channel", "connection_id", "status", "address", "consent" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment": { "$ref": "#/components/schemas/Environment" }, "subscriber_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "notifier_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "channel": { "const": "email" }, "connection_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "status": { "enum": ["active", "paused", "revoked"] }, "address": { "$ref": "#/components/schemas/EmailAddress", "description": "The email destination asserted by the organization under prior consent." }, "consent": { "type": "object", "required": ["kind", "consented_at", "source"], "properties": { "kind": { "const": "asserted_prior_consent" }, "consented_at": { "$ref": "#/components/schemas/Timestamp" }, "source": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[^\u0000-\u001f-Ÿ

]+$" }, "asserted_at": { "$ref": "#/components/schemas/Timestamp" }, "asserted_by": { "type": "object", "required": ["kind", "id"], "properties": { "kind": { "enum": ["credential", "grant", "session"] }, "id": { "$ref": "#/components/schemas/OpaqueIdentifier" } }, "additionalProperties": false }, "domain_id": { "$ref": "#/components/schemas/OpaqueIdentifier" } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "project_id", "environment", "subscriber_id", "notifier_id", "channel", "connection_id", "status", "consent" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment": { "$ref": "#/components/schemas/Environment" }, "subscriber_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "notifier_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "channel": { "const": "email" }, "connection_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "status": { "enum": ["active", "paused", "revoked"] }, "consent": { "type": "object", "required": [ "kind", "consented_at", "source", "asserted_at", "asserted_by", "domain_id" ], "properties": { "kind": { "const": "asserted_prior_consent" }, "consented_at": { "$ref": "#/components/schemas/Timestamp" }, "source": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[^\u0000-\u001f-Ÿ

]+$" }, "asserted_at": { "$ref": "#/components/schemas/Timestamp" }, "asserted_by": { "type": "object", "required": ["kind", "id"], "properties": { "kind": { "enum": ["credential", "grant", "session"] }, "id": { "$ref": "#/components/schemas/OpaqueIdentifier" } }, "additionalProperties": false }, "domain_id": { "$ref": "#/components/schemas/OpaqueIdentifier" } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Address-free asserted consent captured on a message. The snapshot survives binding deletion; it never claims recipient verification." } ] }, "SubscriptionConnectionSummary": { "type": "object", "description": "The safe identity selected for this authorization. Installation identifiers, numeric provider identifiers, credential references, webhook routes, verifiers, and provider identity digests are never exposed.", "required": ["id", "mode", "display_name", "identity"], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "mode": { "$ref": "#/components/schemas/ChannelConnectionMode" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "identity": { "$ref": "#/components/schemas/ConnectionIdentity" } }, "additionalProperties": false }, "CreateSubscriptionLinkRequest": { "type": "object", "description": "Creates one project- and environment-scoped, single-use authorization link.", "required": ["subscriber_id", "channels"], "properties": { "subscriber_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "notifier_id": { "allOf": [{ "$ref": "#/components/schemas/OpaqueIdentifier" }], "default": "default" }, "channels": { "type": "array", "minItems": 1, "maxItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Channel" } }, "connection_id": { "$ref": "#/components/schemas/OpaqueIdentifier", "description": "The exact channel connection to authorize. Omission asks the service to resolve an unambiguous default or sole compatible connection; it never selects an arbitrary fallback." }, "address": { "$ref": "#/components/schemas/EmailAddress", "description": "The exact recipient address for a server-initiated email verification. It is accepted only when the selected channel is email, stored encrypted, and does not assert consent. Omit it when the recipient will enter the address on the hosted page." }, "return_url": { "type": "string", "format": "uri", "pattern": "^https?://[^\\s]+$", "anyOf": [ { "type": "string", "pattern": "^https://" }, { "type": "string", "pattern": "^http://[^/?#\\s]*\\.test(?::[0-9]{1,5})?(?:[/?#]|$)" } ], "maxLength": 2048, "description": "Untrusted redirect input. HTTPS is required outside synthetic .test fixtures; the service never fetches this URL." }, "expires_in_seconds": { "type": "integer", "minimum": 60, "maximum": 86400, "default": 900 }, "recipient_language": { "$ref": "#/components/schemas/RecipientLanguage", "description": "The recipient language to use unless a provider supplies a supported language for that recipient." } }, "allOf": [ { "if": { "properties": { "address": {} }, "required": ["address"] }, "then": { "properties": { "channels": { "const": ["email"] } } } } ], "additionalProperties": false }, "SubscriptionLink": { "type": "object", "description": "A public subscription-link resource scoped to the authenticated project and environment.", "required": [ "id", "project_id", "environment", "subscriber_id", "notifier_id", "channels", "recipient_language", "status", "created_at", "updated_at", "expires_at", "diagnostic_id" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment": { "$ref": "#/components/schemas/Environment" }, "subscriber_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "notifier_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "channels": { "type": "array", "minItems": 1, "maxItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Channel" } }, "recipient_language": { "$ref": "#/components/schemas/RecipientLanguage" }, "status": { "type": "string", "enum": [ "pending", "activated", "expired", "cancelled", "failed", "revoked" ] }, "authorization_url": { "type": "string", "format": "uri", "pattern": "^https://[^\\s]+$", "maxLength": 2048, "description": "The selected provider's native authorization URL. For newly issued Telegram links it is https://t.me/?start=<43-character opaque token> and contains no tenant identifier or provider secret." }, "connection": { "$ref": "#/components/schemas/SubscriptionConnectionSummary", "description": "The immutable connection selection rendered for this authorization. Absent only on legacy resources issued before channel connections were recorded." }, "binding": { "$ref": "#/components/schemas/BindingSummary" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "expires_at": { "$ref": "#/components/schemas/Timestamp" }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" }, "classified_error": { "$ref": "#/components/schemas/ClassifiedError" }, "cancellation_effective": { "type": "boolean", "description": "Present on cancellation responses; false never claims provider-side deletion." }, "email_verification": { "$ref": "#/components/schemas/EmailVerificationSummary" } }, "allOf": [ { "if": { "type": "object", "properties": { "status": { "const": "pending" } }, "required": ["status"] }, "then": { "type": "object", "required": ["authorization_url"], "properties": { "authorization_url": {} } } }, { "if": { "type": "object", "properties": { "status": { "enum": ["activated", "revoked"] } }, "required": ["status"] }, "then": { "type": "object", "required": ["binding"], "properties": { "binding": {} } } }, { "if": { "type": "object", "properties": { "status": { "const": "failed" } }, "required": ["status"] }, "then": { "type": "object", "required": ["classified_error"], "properties": { "classified_error": {} } } } ], "additionalProperties": false }, "CreateMessageRequest": { "type": "object", "description": "Creates one logical message for one subscriber and one resolved channel binding.", "required": ["to", "content"], "properties": { "to": { "$ref": "#/components/schemas/MessageTarget" }, "notifier_id": { "allOf": [{ "$ref": "#/components/schemas/OpaqueIdentifier" }], "default": "default" }, "delivery_target": { "$ref": "#/components/schemas/MessageDeliveryTarget", "description": "Optional routing override. Simulator delivery and the reserved test: subscriber prefix are test-environment-only; live requests are refused with 400 request_invalid. Omit for notifier-default connection delivery or the reserved test-environment simulator default." }, "connection_id": { "allOf": [{ "$ref": "#/components/schemas/OpaqueIdentifier" }], "description": "Optional fail-closed constraint for a visible connection test. The selected subscriber binding and notifier route must resolve to this exact connection; the service never substitutes another connection or provider." }, "content": { "$ref": "#/components/schemas/MessageContent" }, "expires_at": { "$ref": "#/components/schemas/Timestamp", "description": "Optional server-authoritative expiry no more than 24 hours after acceptance." }, "correlation_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "interaction": { "$ref": "#/components/schemas/InteractionRequest" } }, "allOf": [ { "if": { "required": ["connection_id"], "properties": { "connection_id": true } }, "then": { "required": ["delivery_target"], "properties": { "delivery_target": { "const": "connection" } } } } ], "additionalProperties": false }, "DeliveryAttemptSummary": { "type": "object", "description": "A safe aggregate of delivery attempts. Protected provider responses are excluded.", "required": [ "attempt_count", "highest_proven_provider_state", "retry_scheduled" ], "properties": { "attempt_count": { "type": "integer", "minimum": 0 }, "highest_proven_provider_state": { "$ref": "#/components/schemas/HighestProvenProviderState" }, "provider_outcome": { "type": "string", "enum": [ "delivered", "delayed", "hard_bounce", "complained", "suppressed", "failed" ], "description": "The latest authenticated post-acceptance provider outcome. Absence means no such outcome has been recorded." }, "retry_scheduled": { "type": "boolean" }, "retry_at": { "$ref": "#/components/schemas/Timestamp" }, "classified_error": { "$ref": "#/components/schemas/ClassifiedError" } }, "allOf": [ { "if": { "type": "object", "properties": { "retry_scheduled": { "const": true } }, "required": ["retry_scheduled"] }, "then": { "type": "object", "required": ["retry_at"], "properties": { "retry_at": {} } }, "else": { "type": "object", "properties": { "retry_at": false } } } ], "additionalProperties": false }, "Message": { "type": "object", "description": "A project- and environment-scoped logical message and its highest proven delivery outcome.", "required": [ "id", "project_id", "environment", "subscriber_id", "notifier_id", "binding", "delivery_target", "state", "accepted_at", "updated_at", "expires_at", "delivery", "diagnostic_id" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment": { "$ref": "#/components/schemas/Environment" }, "subscriber_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "notifier_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "binding": { "$ref": "#/components/schemas/BindingSummary" }, "binding_resolution": { "type": "string", "enum": ["preferred", "notifier_default"], "description": "How the exact binding was selected. A present but unavailable preference refuses message creation and therefore never appears as notifier_default fallback." }, "broadcast": { "$ref": "#/components/schemas/BroadcastMessageProvenance" }, "delivery_target": { "$ref": "#/components/schemas/MessageDeliveryTarget" }, "state": { "$ref": "#/components/schemas/MessageState" }, "accepted_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "expires_at": { "$ref": "#/components/schemas/Timestamp" }, "delivery": { "$ref": "#/components/schemas/DeliveryAttemptSummary" }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" }, "correlation_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "interaction": { "$ref": "#/components/schemas/InteractionSummary" }, "cancellation_effective": { "type": "boolean", "description": "Present on cancellation responses. False means the provider call was already owned and no deletion is claimed." }, "outcome_guidance": { "type": "string", "const": "Delivery may have been accepted by the provider. No automatic retry is scheduled; create a new message explicitly if another attempt is appropriate." } }, "allOf": [ { "if": { "type": "object", "properties": { "state": { "const": "outcome_unknown" } }, "required": ["state"] }, "then": { "type": "object", "required": ["outcome_guidance"], "properties": { "outcome_guidance": {}, "delivery": { "allOf": [ { "$ref": "#/components/schemas/DeliveryAttemptSummary" }, { "type": "object", "required": ["classified_error"], "properties": { "attempt_count": { "type": "integer", "minimum": 1 }, "highest_proven_provider_state": { "const": "none" }, "retry_scheduled": { "const": false }, "classified_error": { "allOf": [ { "$ref": "#/components/schemas/ClassifiedError" }, { "type": "object", "properties": { "code": { "const": "provider_outcome_unknown" }, "retryable": { "const": false } } } ] } } } ] } } } }, { "if": { "type": "object", "properties": { "state": { "enum": [ "accepted", "dispatch_pending", "queued", "sending", "provider_accepted", "cancelled", "expired" ] } }, "required": ["state"] }, "then": { "type": "object", "properties": { "delivery": { "allOf": [ { "$ref": "#/components/schemas/DeliveryAttemptSummary" }, { "type": "object", "properties": { "classified_error": false } } ] } } } }, { "if": { "type": "object", "properties": { "state": { "not": { "const": "provider_accepted" } } }, "required": ["state"] }, "then": { "type": "object", "properties": { "delivery": { "allOf": [ { "$ref": "#/components/schemas/DeliveryAttemptSummary" }, { "type": "object", "properties": { "highest_proven_provider_state": { "const": "none" } } } ] } } } }, { "if": { "type": "object", "properties": { "state": { "not": { "const": "retry_wait" } } }, "required": ["state"] }, "then": { "type": "object", "properties": { "delivery": { "allOf": [ { "$ref": "#/components/schemas/DeliveryAttemptSummary" }, { "type": "object", "properties": { "retry_scheduled": { "const": false } } } ] } } } }, { "if": { "type": "object", "properties": { "state": { "const": "provider_accepted" } }, "required": ["state"] }, "then": { "type": "object", "properties": { "delivery": { "allOf": [ { "$ref": "#/components/schemas/DeliveryAttemptSummary" }, { "type": "object", "properties": { "attempt_count": { "type": "integer", "minimum": 1 }, "highest_proven_provider_state": { "const": "provider_accepted" } } } ] } } } }, { "if": { "type": "object", "properties": { "state": { "const": "retry_wait" } }, "required": ["state"] }, "then": { "type": "object", "properties": { "delivery": { "allOf": [ { "$ref": "#/components/schemas/DeliveryAttemptSummary" }, { "type": "object", "required": ["classified_error"], "properties": { "attempt_count": { "type": "integer", "minimum": 1 }, "retry_scheduled": { "const": true }, "classified_error": { "allOf": [ { "$ref": "#/components/schemas/ClassifiedError" }, { "type": "object", "properties": { "code": { "const": "provider_retryable" }, "retryable": { "const": true } } } ] } } } ] } } } }, { "if": { "type": "object", "properties": { "state": { "const": "terminal_failed" } }, "required": ["state"] }, "then": { "type": "object", "properties": { "delivery": { "allOf": [ { "$ref": "#/components/schemas/DeliveryAttemptSummary" }, { "type": "object", "required": ["classified_error"], "properties": { "attempt_count": { "type": "integer", "minimum": 1 }, "classified_error": { "allOf": [ { "$ref": "#/components/schemas/ClassifiedError" }, { "type": "object", "properties": { "code": { "const": "provider_terminal" }, "retryable": { "const": false } } } ] } } } ] } } } }, { "if": { "type": "object", "properties": { "state": { "const": "sending" } }, "required": ["state"] }, "then": { "type": "object", "properties": { "delivery": { "allOf": [ { "$ref": "#/components/schemas/DeliveryAttemptSummary" }, { "type": "object", "properties": { "attempt_count": { "type": "integer", "minimum": 1 } } } ] } } } }, { "if": { "type": "object", "properties": { "state": { "enum": ["sending", "provider_accepted", "outcome_unknown"] }, "cancellation_effective": { "type": "boolean" } }, "required": ["state", "cancellation_effective"] }, "then": { "type": "object", "properties": { "cancellation_effective": { "const": false } } } } ], "additionalProperties": false }, "Problem": { "type": "object", "description": "Safe RFC 9457-style Problem Details for the WhooshBang API.", "required": [ "type", "title", "status", "detail", "code", "diagnostic_id", "retryable" ], "properties": { "type": { "type": "string", "format": "uri", "pattern": "^https://whooshbang\\.flowxo\\.com/problems/[a-z][a-z0-9_]*$" }, "title": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "detail": { "type": "string", "minLength": 1, "maxLength": 1024 }, "code": { "$ref": "#/components/schemas/ProblemCode" }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" }, "retryable": { "type": "boolean" }, "retry_at": { "$ref": "#/components/schemas/Timestamp" }, "field_errors": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/ProblemFieldError" } }, "provider_failure": { "$ref": "#/components/schemas/ProviderFailure", "description": "Present only when a provider operation caused the problem. Safe guidance stays in `detail`; provider wire detail is structurally absent." } }, "allOf": [ { "if": { "type": "object", "properties": { "retryable": { "const": false } }, "required": ["retryable"] }, "then": { "type": "object", "properties": { "retry_at": false } } } ], "oneOf": [ { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/authentication_required" }, "title": { "const": "Authentication required" }, "status": { "const": 401 }, "code": { "const": "authentication_required" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/replay_unavailable" }, "title": { "const": "Replay unavailable" }, "status": { "const": 409 }, "code": { "const": "replay_unavailable" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/endpoint_rotation_conflict" }, "title": { "const": "Endpoint rotation conflict" }, "status": { "const": 409 }, "code": { "const": "endpoint_rotation_conflict" }, "retryable": { "const": true } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/project_slug_conflict" }, "title": { "const": "Project slug conflict" }, "status": { "const": 409 }, "code": { "const": "project_slug_conflict" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/credential_invalid" }, "title": { "const": "Credential invalid" }, "status": { "const": 401 }, "code": { "const": "credential_invalid" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/scope_forbidden" }, "title": { "const": "Scope forbidden" }, "status": { "const": 403 }, "code": { "const": "scope_forbidden" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/environment_mismatch" }, "title": { "const": "Environment mismatch" }, "status": { "const": 403 }, "code": { "const": "environment_mismatch" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/idempotency_key_required" }, "title": { "const": "Idempotency key required" }, "status": { "const": 400 }, "code": { "const": "idempotency_key_required" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/idempotency_conflict" }, "title": { "const": "Idempotency conflict" }, "status": { "const": 409 }, "code": { "const": "idempotency_conflict" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/privacy_operation_in_progress" }, "title": { "const": "Privacy operation in progress" }, "status": { "const": 409 }, "code": { "const": "privacy_operation_in_progress" }, "retryable": { "const": true } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/request_invalid" }, "title": { "const": "Request invalid" }, "status": { "const": 400 }, "code": { "const": "request_invalid" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/subscriber_unbound" }, "title": { "const": "Subscriber unbound" }, "status": { "const": 422 }, "code": { "const": "subscriber_unbound" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/recipient_configuration_invalid" }, "title": { "const": "Recipient configuration invalid" }, "status": { "const": 409 }, "code": { "const": "recipient_configuration_invalid" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/recipient_origin_forbidden" }, "title": { "const": "Recipient origin forbidden" }, "status": { "const": 403 }, "code": { "const": "recipient_origin_forbidden" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/return_destination_not_found" }, "title": { "const": "Return destination not found" }, "status": { "const": 422 }, "code": { "const": "return_destination_not_found" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/recipient_capability_invalid" }, "title": { "const": "Recipient capability invalid" }, "status": { "const": 401 }, "code": { "const": "recipient_capability_invalid" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/recipient_handoff_invalid" }, "title": { "const": "Recipient handoff invalid" }, "status": { "const": 404 }, "code": { "const": "recipient_handoff_invalid" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/preferred_binding_conflict" }, "title": { "const": "Preferred binding conflict" }, "status": { "const": 409 }, "code": { "const": "preferred_binding_conflict" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/preferred_binding_unavailable" }, "title": { "const": "Preferred binding unavailable" }, "status": { "const": 422 }, "code": { "const": "preferred_binding_unavailable" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/subscriber_conflict" }, "title": { "const": "Subscriber conflict" }, "status": { "const": 409 }, "code": { "const": "subscriber_conflict" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/recipient_group_conflict" }, "title": { "const": "Recipient group conflict" }, "status": { "const": 409 }, "code": { "const": "recipient_group_conflict" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/recipient_group_archived" }, "title": { "const": "Recipient group archived" }, "status": { "const": 409 }, "code": { "const": "recipient_group_archived" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/resource_not_found" }, "title": { "const": "Resource not found" }, "status": { "const": 404 }, "code": { "const": "resource_not_found" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/resource_expired" }, "title": { "const": "Resource expired" }, "status": { "const": 404 }, "code": { "const": "resource_expired" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/cancellation_too_late" }, "title": { "const": "Cancellation too late" }, "status": { "const": 409 }, "code": { "const": "cancellation_too_late" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/credential_organization_mismatch" }, "title": { "const": "Credential organization mismatch" }, "status": { "const": 403 }, "code": { "const": "credential_organization_mismatch" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/rate_limited" }, "title": { "const": "Rate limited" }, "status": { "const": 429 }, "code": { "const": "rate_limited" }, "retryable": { "const": true } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/provider_retryable" }, "title": { "const": "Provider retryable failure" }, "status": { "const": 503 }, "code": { "const": "provider_retryable" }, "retryable": { "const": true } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/provider_terminal" }, "title": { "const": "Provider terminal failure" }, "status": { "const": 502 }, "code": { "const": "provider_terminal" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/provider_outcome_unknown" }, "title": { "const": "Provider outcome unknown" }, "status": { "const": 502 }, "code": { "const": "provider_outcome_unknown" }, "retryable": { "const": false } } }, { "type": "object", "properties": { "type": { "const": "https://whooshbang.flowxo.com/problems/internal_error" }, "title": { "const": "Internal error" }, "status": { "const": 500 }, "code": { "const": "internal_error" }, "retryable": { "const": true } } } ], "additionalProperties": false }, "InteractionRequest": { "description": "A required-type tagged union. C0 supports confirm, single-select, and input only.", "oneOf": [ { "$ref": "#/components/schemas/ConfirmInteractionRequest" }, { "$ref": "#/components/schemas/SelectInteractionRequest" }, { "$ref": "#/components/schemas/InputInteractionRequest" } ] }, "InteractionSummary": { "type": "object", "description": "The hosted interaction identity and first-terminal-writer state.", "required": ["id", "type", "state", "expires_at"], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier-2" }, "type": { "type": "string", "enum": ["confirm", "select", "input"] }, "state": { "$ref": "#/components/schemas/InteractionState" }, "expires_at": { "$ref": "#/components/schemas/Timestamp-2" }, "correlation_id": { "$ref": "#/components/schemas/InteractionCorrelationId" }, "answered_at": { "$ref": "#/components/schemas/Timestamp-2" }, "answer_retained": { "type": "boolean", "description": "Whether the typed answer remains available inside its content-retention window. False preserves the answered terminal fact after answer deletion." }, "answer": { "oneOf": [ { "type": "boolean" }, { "type": "string", "minLength": 1, "maxLength": 4000 } ] } }, "allOf": [ { "if": { "properties": { "state": { "const": "answered" } }, "required": ["state"] }, "then": { "required": ["answered_at", "answer_retained"], "properties": { "answered_at": {}, "answer_retained": {}, "answer": {} }, "allOf": [ { "if": { "properties": { "answer_retained": { "const": true } }, "required": ["answer_retained"] }, "then": { "required": ["answer"], "properties": { "answer": {} } }, "else": { "properties": { "answer": false } } } ] }, "else": { "properties": { "answered_at": false, "answer_retained": false, "answer": false } } }, { "if": { "properties": { "type": { "const": "confirm" } }, "required": ["type"] }, "then": { "properties": { "answer": { "type": "boolean" } } } }, { "if": { "properties": { "type": { "const": "select" } }, "required": ["type"] }, "then": { "properties": { "answer": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\u0000-\\u001F\\u007F]+$" } } } }, { "if": { "properties": { "type": { "const": "input" } }, "required": ["type"] }, "then": { "properties": { "answer": { "$ref": "#/components/schemas/TrimmedInputAnswer" } } } } ], "additionalProperties": false }, "InteractionEvent": { "type": "object", "description": "An authenticated, immutable human-answer fact. It is data for the consumer and never a command or proof of business success.", "required": [ "schema", "id", "cursor", "type", "message_id", "interaction_id", "channel_context", "occurred_at", "expires_at" ], "properties": { "schema": { "const": "whooshbang.interaction-event.v1" }, "id": { "$ref": "#/components/schemas/OpaqueIdentifier-2" }, "cursor": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^mcur_[A-Za-z0-9_-]+$", "description": "The opaque position of this event in the authenticated machine stream." }, "type": { "const": "interaction.received" }, "message_id": { "$ref": "#/components/schemas/OpaqueIdentifier-2" }, "interaction_id": { "$ref": "#/components/schemas/OpaqueIdentifier-2" }, "correlation_id": { "$ref": "#/components/schemas/InteractionCorrelationId" }, "response": { "$ref": "#/components/schemas/InteractionResponse" }, "answer_retained": { "type": "boolean", "description": "False means the content window closed and response was removed. New retained events publish true; a retained legacy event may omit this member during rolling deployment." }, "channel_context": { "$ref": "#/components/schemas/SafeChannelContext" }, "occurred_at": { "$ref": "#/components/schemas/Timestamp-2" }, "expires_at": { "$ref": "#/components/schemas/Timestamp-2" } }, "allOf": [ { "if": { "properties": { "answer_retained": { "const": false } }, "required": ["answer_retained"] }, "then": { "properties": { "response": false } }, "else": { "properties": { "response": { "$ref": "#/components/schemas/InteractionResponse" } }, "required": ["response"] } } ], "additionalProperties": false }, "CreateMachineClientRequest": { "type": "object", "required": ["machine_id", "notifier_id", "subscriber_id"], "properties": { "machine_id": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[^\\u0000-\\u001F\\u007F]+$" }, "notifier_id": { "$ref": "#/components/schemas/OpaqueIdentifier-3" }, "subscriber_id": { "$ref": "#/components/schemas/OpaqueIdentifier-3" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 120 } }, "additionalProperties": false }, "MachineClient": { "type": "object", "required": [ "id", "project_id", "environment", "machine_id", "notifier_id", "subscriber_id", "binding_id", "status", "scope_summary", "created_at", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier-3" }, "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier-3" }, "environment": { "$ref": "#/components/schemas/Environment-2" }, "machine_id": { "$ref": "#/components/schemas/OpaqueIdentifier-3" }, "notifier_id": { "$ref": "#/components/schemas/OpaqueIdentifier-3" }, "subscriber_id": { "$ref": "#/components/schemas/OpaqueIdentifier-3" }, "binding_id": { "$ref": "#/components/schemas/OpaqueIdentifier-3" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": ["provisioning", "active", "revoked"] }, "scope_summary": { "$ref": "#/components/schemas/MachineScopeSummary" }, "created_at": { "$ref": "#/components/schemas/Timestamp-2" }, "updated_at": { "$ref": "#/components/schemas/Timestamp-2" }, "last_used_at": { "$ref": "#/components/schemas/Timestamp-2" }, "revoked_at": { "$ref": "#/components/schemas/Timestamp-2" } }, "allOf": [ { "if": { "properties": { "status": { "const": "revoked" } }, "required": ["status"] }, "then": { "required": ["revoked_at"], "properties": { "revoked_at": {} } }, "else": { "properties": { "revoked_at": false } } } ], "additionalProperties": false }, "MachineCredentialId": { "type": "string", "pattern": "^mcred_[A-Za-z0-9_-]{21}[AQgw]$", "description": "mcred_ followed by the canonical unpadded base64url encoding of exactly 16 random bytes." }, "RegisterMachineCredentialRequest": { "type": "object", "required": ["credential_id", "secret_sha256"], "properties": { "credential_id": { "$ref": "#/components/schemas/MachineCredentialId" }, "secret_sha256": { "$ref": "#/components/schemas/MachineSecretDigest" } }, "additionalProperties": false }, "MachineCredential": { "type": "object", "required": [ "credential_id", "machine_client_id", "status", "scope_summary", "created_at" ], "properties": { "credential_id": { "$ref": "#/components/schemas/MachineCredentialId" }, "machine_client_id": { "$ref": "#/components/schemas/OpaqueIdentifier-3" }, "status": { "type": "string", "enum": ["active", "revoked"] }, "scope_summary": { "$ref": "#/components/schemas/MachineScopeSummary" }, "created_at": { "$ref": "#/components/schemas/Timestamp-2" }, "last_used_at": { "$ref": "#/components/schemas/Timestamp-2" }, "revoked_at": { "$ref": "#/components/schemas/Timestamp-2" } }, "allOf": [ { "if": { "properties": { "status": { "const": "revoked" } }, "required": ["status"] }, "then": { "required": ["revoked_at"], "properties": { "revoked_at": {} } }, "else": { "properties": { "revoked_at": false } } } ], "additionalProperties": false }, "MachineCursor": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^mcur_[A-Za-z0-9_-]+$", "description": "An opaque position within only the authenticated machine stream." }, "MachineEventPollResponse": { "type": "object", "required": ["schema", "events", "committed_cursor", "server_time"], "properties": { "schema": { "const": "whooshbang.machine-events.v1" }, "events": { "type": "array", "maxItems": 50, "x-unique-property": "cursor", "items": { "$ref": "#/components/schemas/InteractionEvent" } }, "committed_cursor": { "oneOf": [ { "$ref": "#/components/schemas/MachineCursor" }, { "type": "null" } ] }, "server_time": { "$ref": "#/components/schemas/Timestamp-2" } }, "additionalProperties": false }, "MachineEventAckRequest": { "type": "object", "required": ["cursor", "disposition"], "properties": { "cursor": { "$ref": "#/components/schemas/MachineCursor" }, "disposition": { "$ref": "#/components/schemas/MachineEventAckDisposition" }, "reason_code": { "oneOf": [ { "$ref": "#/components/schemas/QuarantineReasonCode" }, { "type": "null" } ] } }, "allOf": [ { "if": { "properties": { "disposition": { "const": "quarantined" } }, "required": ["disposition"] }, "then": { "required": ["reason_code"], "properties": { "reason_code": { "$ref": "#/components/schemas/QuarantineReasonCode" } } }, "else": { "properties": { "reason_code": { "type": "null" } } } } ], "additionalProperties": false }, "MachineEventAckResponse": { "type": "object", "required": [ "event_id", "cursor", "disposition", "acknowledgement_status", "committed_cursor", "advanced" ], "properties": { "event_id": { "$ref": "#/components/schemas/OpaqueIdentifier-3" }, "cursor": { "$ref": "#/components/schemas/MachineCursor" }, "disposition": { "$ref": "#/components/schemas/MachineEventAckDisposition" }, "reason_code": { "$ref": "#/components/schemas/QuarantineReasonCode" }, "acknowledgement_status": { "type": "string", "enum": ["recorded", "existing"] }, "committed_cursor": { "oneOf": [ { "$ref": "#/components/schemas/MachineCursor" }, { "type": "null" } ] }, "advanced": { "type": "boolean" } }, "allOf": [ { "if": { "properties": { "disposition": { "const": "quarantined" } }, "required": ["disposition"] }, "then": { "required": ["reason_code"], "properties": { "reason_code": {} } }, "else": { "properties": { "reason_code": false } } } ], "additionalProperties": false }, "ProviderCapabilities": { "$ref": "#/components/schemas/provider-capabilities-v1.schema" }, "ProviderCapabilitiesCollection": { "type": "object", "required": ["schema", "providers"], "properties": { "schema": { "const": "whooshbang.provider-capabilities-collection.v1" }, "providers": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/provider-capabilities-v1.schema" }, "x-unique-property": "provider" }, "total": { "$ref": "#/components/schemas/ListTotal" } }, "additionalProperties": false }, "ProviderInstallationCollection": { "type": "object", "required": ["authorization_available", "items", "total"], "properties": { "authorization_available": { "type": "boolean", "description": "Whether this deployment is configured to start or reconnect customer-owned provider authorization. False is a deployment capability, never evidence about a tenant or credential." }, "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/ProviderInstallation" } }, "next_cursor": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" }, "page": { "$ref": "#/components/schemas/ListPageNumber" }, "page_size": { "$ref": "#/components/schemas/ListPageSize" }, "total": { "$ref": "#/components/schemas/ListTotal" } }, "additionalProperties": false }, "ProviderInstallation": { "type": "object", "description": "An account-owned provider installation. Its WhooshBang id is safe to use only under the authenticated organization scope; provider team ids, OAuth grants, scopes and credentials are absent.", "required": [ "id", "provider", "display_name", "status", "health", "created_at", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "provider": { "const": "email" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "status": { "$ref": "#/components/schemas/ProviderInstallationStatus" }, "health": { "$ref": "#/components/schemas/ProviderHealthState" }, "failure": { "$ref": "#/components/schemas/ProviderFailure" }, "authorization_setup": { "$ref": "#/components/schemas/ProviderAuthorizationSetup", "description": "Short-lived, credential-free OAuth progress for this account installation. Present only while an authorization or reauthorization attempt is resumable or needs a bounded explanation." }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" } }, "additionalProperties": false }, "CreateProviderInstallationRequest": { "type": "object", "description": "Starts a customer-owned email provider authorization. The display name is WhooshBang-local presentation and is never sent to the provider.", "required": ["display_name"], "properties": { "display_name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "additionalProperties": false }, "EmailDomainCollection": { "type": "object", "required": ["items", "total"], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/EmailDomain" } }, "next_cursor": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" }, "page": { "$ref": "#/components/schemas/ListPageNumber" }, "page_size": { "$ref": "#/components/schemas/ListPageSize" }, "total": { "$ref": "#/components/schemas/ListTotal" } }, "additionalProperties": false }, "EmailDomain": { "type": "object", "description": "An account-owned email domain. Every identifier is a WhooshBang identifier checked under the authenticated organization; provider domain and team identifiers, credentials, raw events and provider errors are absent.", "required": [ "id", "installation_id", "domain", "lifecycle", "capabilities", "dns_records", "guide", "health", "delivery_policy", "created_at", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "installation_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "authorized_connection_ids": { "type": "array", "maxItems": 100, "uniqueItems": true, "items": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "description": "The project/environment connections currently authorized through tenant-checked edges to use this domain. One verified domain may authorize distinct test and live connections without repeating DNS setup." }, "domain": { "$ref": "#/components/schemas/EmailDomainName" }, "lifecycle": { "$ref": "#/components/schemas/EmailDomainLifecycle" }, "capabilities": { "$ref": "#/components/schemas/EmailDomainCapabilities" }, "dns_records": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/EmailDnsRecord" } }, "guide": { "$ref": "#/components/schemas/EmailDomainGuide" }, "health": { "$ref": "#/components/schemas/ProviderHealthState" }, "delivery_policy": { "$ref": "#/components/schemas/EmailDeliveryPolicy" }, "failure": { "$ref": "#/components/schemas/ProviderFailure" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" } }, "additionalProperties": false }, "CreateEmailDomainRequest": { "type": "object", "description": "Creates or safely adopts one dedicated domain inside an authorized account-owned installation. No provider team id, API key or OAuth credential can be supplied.", "required": ["installation_id", "domain"], "properties": { "installation_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "domain": { "$ref": "#/components/schemas/EmailDomainName" }, "tls": { "enum": ["opportunistic", "enforced"], "default": "opportunistic" } }, "additionalProperties": false }, "CreateEmailBindingImportRequest": { "type": "object", "description": "Creates one durable import scoped by the authenticated organization and the project/environment route. Every row delegates to the ordinary binding operation so imports cannot bypass consent, uniqueness, hold or tenant checks.", "required": ["connection_id", "rows"], "properties": { "connection_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "rows": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "$ref": "#/components/schemas/EmailBindingImportRow" } } }, "additionalProperties": false }, "EmailBindingImportJob": { "type": "object", "required": [ "id", "organization_id", "project_id", "environment_id", "environment", "connection_id", "status", "total_rows", "processed_rows", "succeeded_rows", "failed_rows", "failures", "created_at", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "organization_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment": { "$ref": "#/components/schemas/Environment" }, "connection_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "status": { "enum": ["pending", "running", "completed", "failed", "cancelled"] }, "total_rows": { "type": "integer", "minimum": 1, "maximum": 1000 }, "processed_rows": { "type": "integer", "minimum": 0, "maximum": 1000 }, "succeeded_rows": { "type": "integer", "minimum": 0, "maximum": 1000 }, "failed_rows": { "type": "integer", "minimum": 0, "maximum": 1000 }, "failures": { "type": "array", "maxItems": 1000, "items": { "type": "object", "description": "One rejected import row. The zero-based row index lets a caller correct and retry only that row; the bounded code and detail use the same safe vocabulary as ordinary request field errors.", "required": ["row_index", "code", "detail"], "properties": { "row_index": { "type": "integer", "minimum": 0, "maximum": 999 }, "code": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*$" }, "detail": { "type": "string", "minLength": 1, "maxLength": 512 } }, "additionalProperties": false }, "description": "Bounded row-level refusals. Completed imports report enough detail to identify and correct each rejected row without resubmitting successful rows." }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" } }, "additionalProperties": false }, "ProjectRecipientExperience": { "type": "object", "description": "The project-owned recipient identity and fallback locale.", "required": [ "project_id", "default_locale", "brand", "row_version", "updated_at", "diagnostic_id" ], "properties": { "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "default_locale": { "$ref": "#/components/schemas/RecipientLanguage" }, "brand": { "$ref": "#/components/schemas/RecipientBrand" }, "row_version": { "type": "integer", "minimum": 1 }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" } }, "additionalProperties": false }, "RecipientBrandAssetId": { "type": "string", "pattern": "^asset_[0-9a-f]{32}$", "description": "An opaque identifier for one normalized project-owned recipient brand logo." }, "RecipientBrandLogoAsset": { "type": "object", "description": "Metadata for normalized PNG bytes hosted by WhooshBang. Original upload bytes are never served.", "required": [ "id", "content_type", "width", "height", "sha256", "created_at" ], "properties": { "id": { "$ref": "#/components/schemas/RecipientBrandAssetId" }, "content_type": { "type": "string", "const": "image/png" }, "width": { "type": "integer", "minimum": 1, "maximum": 512 }, "height": { "type": "integer", "minimum": 1, "maximum": 512 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "created_at": { "$ref": "#/components/schemas/Timestamp" } }, "additionalProperties": false }, "RecipientBrandLogoUpload": { "type": "object", "description": "The normalized asset and project configuration atomically updated to use it.", "required": ["asset", "configuration"], "properties": { "asset": { "$ref": "#/components/schemas/RecipientBrandLogoAsset" }, "configuration": { "$ref": "#/components/schemas/ProjectRecipientExperience" } }, "additionalProperties": false }, "NotificationImageAssetId": { "type": "string", "pattern": "^asset_[0-9a-f]{32}$", "description": "An opaque immutable version identity for one environment-owned notification image." }, "NotificationImage": { "type": "object", "description": "One optional provider-neutral illustrative image. The notification content remains complete without the pixels.", "required": ["asset_id", "purpose", "description"], "properties": { "asset_id": { "$ref": "#/components/schemas/NotificationImageAssetId" }, "purpose": { "const": "illustration" }, "description": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "^(?=.*\\S)[^\\u0000-\\u001F\\u007F]+$", "x-max-utf8-bytes": 4000, "description": "Durable accessible meaning that every adapter preserves independently of native image support." } }, "additionalProperties": false }, "NotificationImageAsset": { "type": "object", "description": "Safe metadata for one immutable canonical PNG held in the exact project environment. Original upload bytes are never served.", "required": [ "id", "content_type", "byte_size", "width", "height", "sha256", "created_at", "expires_at" ], "properties": { "id": { "$ref": "#/components/schemas/NotificationImageAssetId" }, "content_type": { "type": "string", "const": "image/png" }, "byte_size": { "type": "integer", "minimum": 1, "maximum": 524288 }, "width": { "type": "integer", "minimum": 1, "maximum": 512 }, "height": { "type": "integer", "minimum": 1, "maximum": 512 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "expires_at": { "$ref": "#/components/schemas/Timestamp", "description": "The end of the 30-day admission window for new notification references." } }, "additionalProperties": false }, "UpdateProjectRecipientExperienceRequest": { "type": "object", "description": "Replaces the complete project-owned recipient experience under the last observed row version.", "required": ["default_locale", "brand", "row_version"], "properties": { "default_locale": { "$ref": "#/components/schemas/RecipientLanguage" }, "brand": { "$ref": "#/components/schemas/RecipientBrand" }, "row_version": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "EnvironmentRecipientExperience": { "type": "object", "description": "One revisioned environment's recipient-connectable channels and exact browser return policy.", "required": [ "project_id", "environment_id", "environment", "revision", "enabled_channels", "connectable_channels", "allowed_origins", "return_destinations", "updated_at", "diagnostic_id" ], "properties": { "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment": { "$ref": "#/components/schemas/Environment" }, "revision": { "type": "integer", "minimum": 1 }, "enabled_channels": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Channel" } }, "connectable_channels": { "type": "array", "maxItems": 8, "uniqueItems": true, "description": "The channels a recipient can complete an authorization on right now: the environment's default notifier routes to a working connection for each. Resolved when this is read, the same way a recipient session resolves it. An enabled channel missing from this list is not offered to recipients until it has a working connection again.", "items": { "$ref": "#/components/schemas/Channel" } }, "allowed_origins": { "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "$ref": "#/components/schemas/ExactOrigin" } }, "return_destinations": { "type": "array", "maxItems": 20, "x-unique-property": "key", "items": { "$ref": "#/components/schemas/ReturnDestination" } }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" } }, "additionalProperties": false }, "UpdateEnvironmentRecipientExperienceRequest": { "type": "object", "description": "Replaces one complete environment recipient policy under its last observed revision.", "required": [ "revision", "enabled_channels", "allowed_origins", "return_destinations" ], "properties": { "revision": { "type": "integer", "minimum": 1 }, "enabled_channels": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Channel" } }, "allowed_origins": { "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "$ref": "#/components/schemas/ExactOrigin" } }, "return_destinations": { "type": "array", "maxItems": 20, "x-unique-property": "key", "items": { "$ref": "#/components/schemas/ReturnDestination" } } }, "additionalProperties": false }, "SubscriberChannelSettings": { "type": "object", "description": "Safe channel settings for one subscriber in the authorized project environment. Management never establishes or revives revoked consent.", "required": ["subscriber_id", "channels", "diagnostic_id"], "properties": { "subscriber_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/RecipientChannelSummary" } }, "preference": { "$ref": "#/components/schemas/PreferredBinding" }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" } }, "additionalProperties": false }, "AcknowledgeEmailRemediationRequest": { "type": "object", "description": "An organization administrator acknowledges that the cause of the email sending hold has been remediated. This never reactivates revoked or suppressed recipients.", "required": ["acknowledged"], "properties": { "acknowledged": { "const": true } }, "additionalProperties": false }, "CreateRecipientSessionRequest": { "type": "object", "description": "Creates one short-lived browser capability for the authenticated project environment and one subscriber. Configuration, channel selection, groups, messages, and arbitrary return URLs are structurally absent.", "required": ["subscriber_id"], "properties": { "subscriber_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "locale": { "$ref": "#/components/schemas/RecipientLanguage" }, "return_to": { "$ref": "#/components/schemas/DeveloperKey" }, "expires_in_seconds": { "type": "integer", "minimum": 300, "maximum": 3600, "default": 900 } }, "additionalProperties": false }, "CreateRecipientSessionResponse": { "type": "object", "description": "The only response that reveals the recipient capability. The hosted URL itself carries no capability in its query string.", "required": ["session", "browser_capability", "hosted_url"], "properties": { "session": { "$ref": "#/components/schemas/RecipientSession" }, "browser_capability": { "$ref": "#/components/schemas/RecipientSessionCapability" }, "hosted_url": { "type": "string", "format": "uri", "const": "https://connect.whooshbang.com/recipient-settings", "maxLength": 2048, "description": "The capability-free exact WhooshBang hosted entry point. The reusable browser capability is never placed in this or any other URL." } }, "additionalProperties": false }, "RecipientSession": { "type": "object", "description": "A browser-safe projection for the exact subscriber selected when the session was created. Organization, project, environment, subscriber, origin, resolved return URL, provider identity, credentials, and group state are structurally absent.", "required": [ "id", "capability_prefix", "state", "configuration_revision", "locale", "brand", "panel_copy", "channels", "operations", "expires_at", "diagnostic_id" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "capability_prefix": { "$ref": "#/components/schemas/RecipientSessionCapabilityPrefix" }, "state": { "type": "string", "enum": ["active", "expired", "revoked"] }, "configuration_revision": { "type": "integer", "minimum": 1 }, "locale": { "$ref": "#/components/schemas/RecipientLanguage" }, "brand": { "$ref": "#/components/schemas/RecipientBrand" }, "panel_copy": { "$ref": "#/components/schemas/RecipientPanelCopyOverrides" }, "channels": { "type": "array", "maxItems": 8, "x-unique-property": "channel", "items": { "$ref": "#/components/schemas/RecipientChannelSummary" } }, "preference": { "$ref": "#/components/schemas/PreferredBinding", "description": "The current exact preference and row version, when one exists. Tenant and subscriber identifiers remain absent." }, "operations": { "type": "array", "minItems": 1, "maxItems": 6, "uniqueItems": true, "items": { "$ref": "#/components/schemas/RecipientSessionOperation" } }, "expires_at": { "$ref": "#/components/schemas/Timestamp" }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" } }, "additionalProperties": false }, "RecipientPanelCopyOverrides": { "type": "object", "description": "Sparse owner-voiced panel copy for the session locale. Mandatory safety, refusal, pause, unavailable, and unsubscribe strings are structurally absent and remain system-owned.", "properties": { "heading": { "type": "string", "minLength": 1, "maxLength": 80 }, "empty": { "type": "string", "minLength": 1, "maxLength": 500 }, "connect": { "type": "string", "minLength": 1, "maxLength": 40 }, "connected": { "type": "string", "minLength": 1, "maxLength": 40 }, "handoffCancelled": { "type": "string", "minLength": 1, "maxLength": 500 }, "loading": { "type": "string", "minLength": 1, "maxLength": 500 }, "prefer": { "type": "string", "minLength": 1, "maxLength": 40 }, "preferenceMoved": { "type": "string", "minLength": 1, "maxLength": 500 }, "preferred": { "type": "string", "minLength": 1, "maxLength": 40 }, "waiting": { "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false }, "CreateProviderHandoffRequest": { "type": "object", "description": "Requests one single-use provider handoff for a channel already enabled by the session's pinned configuration revision.", "required": ["channel", "completion"], "properties": { "channel": { "$ref": "#/components/schemas/Channel" }, "completion": { "$ref": "#/components/schemas/ProviderHandoffCompletionMode" } }, "additionalProperties": false }, "ProviderHandoff": { "type": "object", "description": "One independently expiring, opaque, single-use provider handoff. Callback/provider selection is bound server-side and cannot be substituted by a browser field.", "required": [ "id", "channel", "state", "handoff_url", "completion", "expires_at", "diagnostic_id" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "channel": { "$ref": "#/components/schemas/Channel" }, "state": { "type": "string", "enum": ["pending", "completed", "expired", "consumed"] }, "handoff_url": { "type": "string", "format": "uri", "pattern": "^https://connect\\.whooshbang\\.com/handoffs/wb_rh1\\.rhc_[A-Za-z0-9_-]{22}\\.[A-Za-z0-9_-]{43}$", "maxLength": 2048, "description": "A WhooshBang-hosted exact handoff URL containing an independently random single-use capability. It contains neither the public handoff id, recipient-session capability, nor a caller-selected callback." }, "completion": { "$ref": "#/components/schemas/ProviderHandoffCompletionMode" }, "expires_at": { "$ref": "#/components/schemas/Timestamp" }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" } }, "additionalProperties": false }, "RecipientHandoffCompletion": { "type": "object", "description": "The closed popup/redirect completion payload. A popup accepts it only from WhooshBang's exact hosted origin and after matching the opener nonce.", "required": ["schema", "session_id", "handoff_id", "status", "mode"], "properties": { "schema": { "const": "whooshbang.recipient-handoff-completion.v1" }, "session_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "handoff_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "status": { "type": "string", "enum": ["connected", "cancelled", "failed"] }, "mode": { "type": "string", "enum": ["popup", "redirect"] }, "opener_nonce": { "type": "string", "minLength": 22, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" } }, "allOf": [ { "if": { "properties": { "mode": { "const": "popup" } }, "required": ["mode"] }, "then": { "required": ["opener_nonce"], "properties": { "opener_nonce": {} } }, "else": { "properties": { "opener_nonce": false } } } ], "additionalProperties": false }, "SetPreferredBindingRequest": { "type": "object", "description": "Selects one exact active binding already owned by this session's subscriber and offered by this notifier/environment.", "required": ["binding_id", "row_version"], "properties": { "binding_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "row_version": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "PreferredBinding": { "type": "object", "description": "The recipient's one exact preferred binding for the session's subscriber/notifier. Subscriber and tenant identifiers are intentionally absent from the browser projection.", "required": [ "notifier_id", "binding_id", "connection_id", "channel", "row_version", "updated_at", "diagnostic_id" ], "properties": { "notifier_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "binding_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "connection_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "channel": { "$ref": "#/components/schemas/Channel" }, "row_version": { "type": "integer", "minimum": 1 }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" } }, "additionalProperties": false }, "AssertEmailConsentRequest": { "type": "object", "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" ], "properties": { "subscriber_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "notifier_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "connection_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "domain_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "address": { "$ref": "#/components/schemas/EmailAddress" }, "consented": { "const": true }, "consented_at": { "$ref": "#/components/schemas/Timestamp", "description": "When the application obtained consent; must not be in the future." }, "source": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[^\u0000-\u001f-Ÿ

]+$", "description": "A bounded customer description of where consent was collected. The authenticated asserting actor is recorded by the service, never accepted from this object." } }, "additionalProperties": false }, "CreateSubscriberRequest": { "type": "object", "description": "Creates one subscriber and optional initial static-group memberships in one idempotent transaction. Groups are creation-only input, not a membership replacement operation.", "required": ["subscriber_id"], "properties": { "subscriber_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "locale": { "$ref": "#/components/schemas/RecipientLanguage" }, "time_zone": { "$ref": "#/components/schemas/TimeZone" }, "groups": { "type": "array", "maxItems": 50, "uniqueItems": true, "items": { "$ref": "#/components/schemas/DeveloperKey" } } }, "additionalProperties": false }, "Subscriber": { "type": "object", "description": "An application subscriber with no provider identity or group-member expansion embedded in the resource.", "required": [ "subscriber_id", "created_at", "updated_at", "diagnostic_id" ], "properties": { "subscriber_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "locale": { "$ref": "#/components/schemas/RecipientLanguage" }, "time_zone": { "$ref": "#/components/schemas/TimeZone" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" } }, "additionalProperties": false }, "SubscriberDataExport": { "type": "object", "description": "A complete customer-controller access artifact for one subscriber across every environment in one project. provided_by_subscriber is the Article 20 portable subset; all three record groups together are the Article 15 access copy. WhooshBang-controller records are named but never mixed into the customer export.", "required": [ "format", "generated_at", "controller_scope", "project_id", "environment_ids", "subscriber_id", "provided_by_subscriber", "provided_by_customer", "derived_by_service", "excluded_controller_data" ], "properties": { "format": { "type": "string", "const": "whooshbang.subscriber-data-export.v1" }, "generated_at": { "$ref": "#/components/schemas/Timestamp" }, "controller_scope": { "type": "string", "const": "customer" }, "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment_ids": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/OpaqueIdentifier" } }, "subscriber_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "provided_by_subscriber": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriberDataExportRecord" } }, "provided_by_customer": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriberDataExportRecord" } }, "derived_by_service": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriberDataExportRecord" } }, "excluded_controller_data": { "type": "array", "minItems": 2, "maxItems": 2, "uniqueItems": true, "items": { "$ref": "#/components/schemas/SubscriberDataExportExcludedControllerData" } } }, "additionalProperties": false }, "CloseOrganizationRequest": { "type": "object", "description": "Exact, explicit confirmation that the current organization administrator intends to close the whole organization.", "required": ["confirmation"], "properties": { "confirmation": { "type": "string", "const": "close-organization" } }, "additionalProperties": false }, "OrganizationClosureResult": { "type": "object", "description": "Terminal organization-closure result. Repeating closure returns the same closed_at and any provider-owned resources that still require manual retirement.", "required": ["status", "closed_at", "provider_actions_required"], "properties": { "status": { "type": "string", "const": "closed" }, "closed_at": { "$ref": "#/components/schemas/Timestamp" }, "provider_actions_required": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/OrganizationClosureProviderAction" } } }, "additionalProperties": false }, "CreateRecipientGroupRequest": { "type": "object", "description": "Creates one static, developer-managed recipient group.", "required": ["key", "display_name"], "properties": { "key": { "$ref": "#/components/schemas/DeveloperKey" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 } }, "additionalProperties": false }, "UpdateRecipientGroupRequest": { "type": "object", "description": "Renames or redescribes an active group. Its key and static membership model cannot change.", "required": ["row_version"], "minProperties": 2, "properties": { "row_version": { "type": "integer", "minimum": 1 }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": ["string", "null"], "maxLength": 500 } }, "additionalProperties": false }, "RecipientGroup": { "type": "object", "description": "An environment-scoped static group. Archive is terminal and reserves the immutable key.", "required": [ "id", "project_id", "environment", "key", "display_name", "status", "membership_revision", "row_version", "created_at", "updated_at", "diagnostic_id" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment": { "$ref": "#/components/schemas/Environment" }, "key": { "$ref": "#/components/schemas/DeveloperKey" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "status": { "type": "string", "enum": ["active", "archived"] }, "membership_revision": { "type": "integer", "minimum": 0 }, "row_version": { "type": "integer", "minimum": 1 }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "archived_at": { "$ref": "#/components/schemas/Timestamp" }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" } }, "allOf": [ { "if": { "properties": { "status": { "const": "archived" } }, "required": ["status"] }, "then": { "required": ["archived_at"], "properties": { "archived_at": {} } }, "else": { "properties": { "archived_at": false } } } ], "additionalProperties": false }, "RecipientGroupCollection": { "type": "object", "required": ["items"], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/RecipientGroup" } }, "next_cursor": { "type": "string", "minLength": 8, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" }, "page": { "$ref": "#/components/schemas/ListPageNumber" }, "page_size": { "$ref": "#/components/schemas/ListPageSize" }, "total": { "$ref": "#/components/schemas/ListTotal" } }, "additionalProperties": false }, "RecipientGroupMembership": { "type": "object", "description": "One historical membership generation. Re-adding a removed subscriber creates a larger generation and never revives this one.", "required": [ "group_id", "group_key", "subscriber_id", "generation", "added_revision", "status", "created_at", "updated_at", "diagnostic_id" ], "properties": { "group_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "group_key": { "$ref": "#/components/schemas/DeveloperKey" }, "subscriber_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "generation": { "type": "integer", "minimum": 1 }, "added_revision": { "type": "integer", "minimum": 1 }, "removed_revision": { "type": "integer", "minimum": 2 }, "status": { "type": "string", "enum": ["active", "removed"] }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" } }, "allOf": [ { "if": { "properties": { "status": { "const": "removed" } }, "required": ["status"] }, "then": { "required": ["removed_revision"], "properties": { "removed_revision": {} } } }, { "if": { "properties": { "status": { "const": "active" } }, "required": ["status"] }, "then": { "properties": { "removed_revision": false } } } ], "additionalProperties": false }, "RecipientGroupMembershipCollection": { "type": "object", "required": ["group_key", "membership_revision", "items"], "properties": { "group_key": { "$ref": "#/components/schemas/DeveloperKey" }, "membership_revision": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/RecipientGroupMembership" } }, "next_cursor": { "type": "string", "minLength": 8, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" }, "page": { "$ref": "#/components/schemas/ListPageNumber" }, "page_size": { "$ref": "#/components/schemas/ListPageSize" }, "total": { "$ref": "#/components/schemas/ListTotal" } }, "additionalProperties": false }, "CreateGroupBroadcastRequest": { "type": "object", "description": "Creates one group broadcast using the existing ordinary message envelope. The group target comes only from the path.", "required": ["content"], "properties": { "notifier_id": { "allOf": [{ "$ref": "#/components/schemas/OpaqueIdentifier" }], "default": "default" }, "content": { "$ref": "#/components/schemas/MessageContent" }, "expires_at": { "$ref": "#/components/schemas/Timestamp" }, "correlation_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "interaction": { "$ref": "#/components/schemas/InteractionRequest" } }, "additionalProperties": false }, "GroupBroadcast": { "type": "object", "description": "One durable acceptance against an exact group membership revision. Delivery remains represented by ordinary child messages.", "required": [ "id", "project_id", "environment", "group_id", "group_key", "audience_revision", "status", "aggregate", "accepted_at", "updated_at", "expires_at", "diagnostic_id" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment": { "$ref": "#/components/schemas/Environment" }, "group_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "group_key": { "$ref": "#/components/schemas/DeveloperKey" }, "audience_revision": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": ["accepted", "expanding", "expanded", "complete"] }, "aggregate": { "$ref": "#/components/schemas/BroadcastAggregate" }, "accepted_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "expires_at": { "$ref": "#/components/schemas/Timestamp" }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" } }, "additionalProperties": false }, "OrganizationRole": { "type": "string", "enum": ["admin", "member"], "description": "The stable WhooshBang authorization role projected from the current Clerk organization membership." }, "OrganizationMembershipSummary": { "type": "object", "required": ["role"], "properties": { "role": { "$ref": "#/components/schemas/OrganizationRole" } }, "additionalProperties": false }, "Timestamp": { "type": "string", "format": "date-time", "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])T(?:[01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](?:\\.[0-9]+)?(?:Z|[+-](?:[01][0-9]|2[0-3]):[0-5][0-9])$", "description": "An RFC 3339 timestamp with a UTC offset. The server is authoritative." }, "ProblemCode": { "type": "string", "enum": [ "authentication_required", "credential_invalid", "scope_forbidden", "environment_mismatch", "idempotency_key_required", "idempotency_conflict", "privacy_operation_in_progress", "project_slug_conflict", "request_invalid", "replay_unavailable", "subscriber_unbound", "recipient_configuration_invalid", "recipient_origin_forbidden", "return_destination_not_found", "recipient_capability_invalid", "recipient_handoff_invalid", "preferred_binding_conflict", "preferred_binding_unavailable", "subscriber_conflict", "recipient_group_conflict", "recipient_group_archived", "resource_not_found", "resource_expired", "cancellation_too_late", "credential_organization_mismatch", "endpoint_rotation_conflict", "rate_limited", "provider_retryable", "provider_terminal", "provider_outcome_unknown", "internal_error" ] }, "ProblemFieldError": { "type": "object", "required": ["field", "code", "detail"], "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 256, "description": "A bounded JSON Pointer or request field identifier." }, "code": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*$" }, "detail": { "type": "string", "minLength": 1, "maxLength": 512 } }, "additionalProperties": false }, "ProviderFailure": { "description": "A provider-neutral failure whose code is valid for the named public operation. The discriminated arms keep machine handling reliable without exposing provider wire vocabulary.", "oneOf": [ { "type": "object", "required": ["operation", "code"], "properties": { "operation": { "const": "setup" }, "code": { "enum": [ "capability_missing", "installation_invalid", "provider_unavailable", "provider_rate_limited", "provider_rejected", "provider_outcome_unknown" ] } }, "additionalProperties": false }, { "type": "object", "required": ["operation", "code"], "properties": { "operation": { "const": "authorization" }, "code": { "enum": [ "authorization_denied", "authorization_expired", "authorization_pending_approval", "authorization_permission_missing", "installation_invalid", "connection_removed", "whooshbang_configuration", "workspace_mismatch", "refresh_outcome_unknown", "reauthorization_required", "installation_revoked", "provider_cleanup_required", "provider_unavailable", "provider_rate_limited", "provider_rejected", "provider_outcome_unknown" ] } }, "additionalProperties": false }, { "type": "object", "required": ["operation", "code"], "properties": { "operation": { "const": "domain" }, "code": { "enum": [ "authorization_permission_missing", "installation_invalid", "refresh_outcome_unknown", "reauthorization_required", "installation_revoked", "domain_invalid", "domain_conflict", "dns_verification_failed", "provider_action_required", "provider_unavailable", "provider_rate_limited", "provider_rejected", "provider_outcome_unknown" ] } }, "additionalProperties": false }, { "type": "object", "required": ["operation", "code"], "properties": { "operation": { "const": "webhook" }, "code": { "enum": [ "authorization_permission_missing", "installation_invalid", "refresh_outcome_unknown", "reauthorization_required", "installation_revoked", "provider_cleanup_required", "webhook_reconciliation_failed", "provider_action_required", "provider_unavailable", "provider_rate_limited", "provider_rejected", "provider_outcome_unknown" ] } }, "additionalProperties": false }, { "type": "object", "required": ["operation", "code"], "properties": { "operation": { "const": "delivery" }, "code": { "enum": [ "authorization_permission_missing", "installation_invalid", "refresh_outcome_unknown", "reauthorization_required", "installation_revoked", "destination_invalid", "destination_suppressed", "hard_bounce", "delivery_held", "provider_action_required", "provider_unavailable", "provider_rate_limited", "provider_rejected", "provider_outcome_unknown" ] } }, "additionalProperties": false }, { "type": "object", "required": ["operation", "code"], "properties": { "operation": { "const": "interaction" }, "code": { "enum": [ "authorization_permission_missing", "installation_invalid", "refresh_outcome_unknown", "reauthorization_required", "installation_revoked", "provider_cleanup_required", "interaction_invalid", "provider_unavailable", "provider_rate_limited", "provider_rejected", "provider_outcome_unknown" ] } }, "additionalProperties": false } ] }, "OrganizationClosureProviderAction": { "type": "object", "description": "One provider-owned resource the customer must retire outside WhooshBang after organization closure. It contains safe identifiers only, never provider credentials.", "required": ["provider", "action", "connection_id"], "properties": { "provider": { "$ref": "#/components/schemas/ChannelConnectionProvider" }, "action": { "type": "string", "enum": ["revoke_bot_token", "delete_provider_application"] }, "connection_id": { "$ref": "#/components/schemas/OpaqueIdentifier" } }, "additionalProperties": false }, "ProviderInstallationStatus": { "type": "string", "enum": [ "pending", "active", "reauthorization_required", "revoked", "invalid" ], "description": "The safe customer-facing lifecycle of a provider installation. Credential and provider-native state stay private." }, "ProviderAuthorizationSetup": { "description": "A credential-free provider authorization handoff for one exact connection. The URL is short-lived and safe to render, but never contains a provider credential, team identifier or raw authorization code; actual OAuth state and callback handling remain service-private.", "oneOf": [ { "type": "object", "required": ["status", "authorization_url", "expires_at"], "properties": { "status": { "const": "awaiting_authorization" }, "authorization_url": { "type": "string", "format": "uri", "pattern": "^https://[^\\s]+$", "maxLength": 2048, "description": "The short-lived HTTPS authorization handoff for this connection. It carries opaque state, not provider credentials or a raw authorization code." }, "expires_at": { "$ref": "#/components/schemas/Timestamp" } }, "additionalProperties": false }, { "type": "object", "required": ["status", "expires_at"], "properties": { "status": { "const": "provisioning" }, "expires_at": { "$ref": "#/components/schemas/Timestamp" } }, "additionalProperties": false }, { "type": "object", "required": ["status", "expires_at", "failure"], "properties": { "status": { "const": "failed" }, "expires_at": { "$ref": "#/components/schemas/Timestamp" }, "failure": { "$ref": "#/components/schemas/ProviderFailure" } }, "additionalProperties": false }, { "type": "object", "required": ["status", "expires_at"], "properties": { "status": { "const": "expired" }, "expires_at": { "$ref": "#/components/schemas/Timestamp" } }, "additionalProperties": false } ] }, "ListPageSize": { "type": "integer", "minimum": 1, "maximum": 100, "description": "The page size that produced `items`, echoed so a caller that sent no `limit` can still divide `total` into pages without knowing the server default." }, "ListTotal": { "type": "integer", "minimum": 0, "description": "How many records the list holds in total, not only on this page. Counted while the page was read, so a write landing between the count and the page can leave it a record or two out of step with `items`. That is noise on an inspection surface; it never changes which records a page addresses." }, "EmailDomainName": { "type": "string", "minLength": 4, "maxLength": 253, "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.){2,}[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$", "description": "A canonical lower-case IDNA ASCII customer sending domain with its trailing dot removed. It must be a dedicated subdomain below the registrable domain; runtime validation uses the public suffix list so a registrable root such as example.co.uk is still rejected. URLs, ports, wildcards and mailbox addresses are invalid." }, "EmailDomainLifecycle": { "type": "string", "enum": [ "requested", "creating", "dns_required", "verifying", "testing", "active", "provider_action_required", "dns_failed", "oauth_required", "held", "deleting", "deleted" ], "description": "The provider-neutral domain lifecycle. Sending and receiving capabilities are reported separately because they verify on different clocks." }, "EmailDomainCapabilityState": { "type": "string", "enum": ["pending", "verified", "failed", "unsupported"] }, "EmailDomainCapabilities": { "type": "object", "required": [ "sending", "receiving", "delivery", "link_interactions", "free_text_reply" ], "properties": { "sending": { "$ref": "#/components/schemas/EmailDomainCapabilityState" }, "receiving": { "$ref": "#/components/schemas/EmailDomainCapabilityState" }, "delivery": { "type": "boolean" }, "link_interactions": { "type": "boolean" }, "free_text_reply": { "type": "boolean", "description": "False when free-text replies cannot be lowered: receiving may not be verified yet, or the provider team may have message-content storage disabled. Delivery and link-based interaction remain independently available; no undocumented eligibility or storage-state endpoint is assumed." } }, "additionalProperties": false }, "EmailDnsRecord": { "description": "One exact neutral DNS record. `name` is preserved exactly as the provider returns it and is relative to the registrable domain (for example `send.notify`, not `send.notify.example.com`).", "oneOf": [ { "type": "object", "required": ["type", "name", "value", "priority", "status"], "properties": { "type": { "const": "MX" }, "name": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^[^\u0000-\u001f-Ÿ

]+$" }, "value": { "type": "string", "minLength": 1, "maxLength": 2048, "pattern": "^[^\u0000-\u001f-Ÿ

]+$" }, "priority": { "type": "integer", "minimum": 0, "maximum": 65535 }, "status": { "enum": [ "not_started", "pending", "verified", "failed", "temporary_failure" ] } }, "additionalProperties": false }, { "type": "object", "required": ["type", "name", "value", "status"], "properties": { "type": { "enum": ["TXT", "CNAME"] }, "name": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^[^\u0000-\u001f-Ÿ

]+$" }, "value": { "type": "string", "minLength": 1, "maxLength": 2048, "pattern": "^[^\u0000-\u001f-Ÿ

]+$" }, "status": { "enum": [ "not_started", "pending", "verified", "failed", "temporary_failure" ] } }, "additionalProperties": false } ] }, "EmailDomainGuide": { "type": "object", "required": ["state"], "properties": { "state": { "enum": [ "detecting", "guided", "domain_connect_available", "complete", "unavailable" ] }, "dns_provider": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[^\u0000-\u001f-Ÿ

]+$" }, "instructions_url": { "type": "string", "format": "uri", "pattern": "^https://[^\\s]+$", "maxLength": 2048, "description": "A short-lived secret-free instruction link for a DNS administrator. It contains no WhooshBang session or provider OAuth material." } }, "allOf": [ { "if": { "properties": { "state": { "enum": ["guided", "domain_connect_available", "complete"] } }, "required": ["state"] }, "then": { "properties": { "dns_provider": true }, "required": ["dns_provider"] }, "else": { "properties": { "dns_provider": false } } } ], "additionalProperties": false }, "EmailSubjectPolicy": { "type": "object", "description": "The fixed subject rendering contract. Notification title wins; otherwise localized copy equivalent to `Notification from {notifier display name}` is used. Whitespace is normalized and the final value is capped at 200 Unicode code points.", "required": ["fallback", "maximum_code_points", "normalize_whitespace"], "properties": { "fallback": { "const": "localized_notifier_name" }, "maximum_code_points": { "const": 200 }, "normalize_whitespace": { "const": true } }, "additionalProperties": false }, "EmailDeliveryPolicy": { "type": "object", "description": "Privacy-safe email defaults. Return-Path and Message-ID remain provider-owned, arbitrary headers are unsupported, and every ordinary message carries a visible management route plus safe one-click unsubscribe semantics when custom headers are available. A GET never mutates consent; the matching POST resolves the exact binding.", "required": [ "open_tracking", "click_tracking", "tls", "unsubscribe", "subject" ], "properties": { "open_tracking": { "const": false }, "click_tracking": { "const": false }, "tls": { "enum": ["opportunistic", "enforced"], "default": "opportunistic" }, "unsubscribe": { "const": "visible_and_one_click_where_supported" }, "subject": { "$ref": "#/components/schemas/EmailSubjectPolicy" } }, "additionalProperties": false }, "OrganizationCredentialPrefix": { "type": "string", "pattern": "^wb_oc1\\.ocred_[A-Za-z0-9_-]{8}$", "description": "A safe display prefix containing the organization-credential format marker and first eight base64url identity characters, never secret bytes." }, "OrganizationCredentialScope": { "type": "string", "enum": [ "organization:read", "projects:write", "projects:read", "messages:write", "messages:read", "subscriptions:write", "subscriptions:read", "machine-clients:write", "machine-clients:read", "capabilities:read", "connections:write", "connections:read" ], "description": "One organization-credential capability. `organization:read` is the organization's project directory — listing the organization's projects and reading one — and is the only scope here a project credential can never carry; it authorizes nothing below the organization. Every other name is the project-credential vocabulary unchanged, and is exercised only on the environment-scoped routes, where the project and environment come from the path and the credential's authority is the intersection of these scopes with the project-credential vocabulary. An organization credential is therefore never wider than a project credential would have been for the same project environment." }, "OrganizationCredentialScopeSet": { "type": "array", "minItems": 1, "maxItems": 12, "uniqueItems": true, "items": { "$ref": "#/components/schemas/OrganizationCredentialScope" } }, "OrganizationCredentialSecret": { "type": "string", "pattern": "^wb_oc1\\.ocred_[A-Za-z0-9_-]{21}[AQgw]\\.[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$", "description": "The exact one-time runtime bearer syntax. The final segment is canonical unpadded base64url for exactly 32 random secret bytes." }, "Environment": { "type": "string", "enum": ["test", "live"], "description": "The single environment selected by the authenticated credential." }, "RecipientCopyOverrideValue": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Customer-authored plain text. The service applies key-specific length and anti-impersonation validation before storage." }, "ApiCredentialPrefix": { "type": "string", "pattern": "^wb_pc1\\.pcred_[A-Za-z0-9_-]{8}$", "description": "A safe display prefix containing the credential format marker and first eight base64url identity characters, never secret bytes." }, "ApiCredentialScope": { "type": "string", "enum": [ "projects:write", "projects:read", "messages:write", "messages:read", "subscriptions:write", "subscriptions:read", "machine-clients:write", "machine-clients:read", "capabilities:read", "connections:write", "connections:read" ], "description": "One project-credential capability. Environment authority always comes from the credential record, never a scope or request field. `projects:write` configures the credential's own project and environment; it never creates a project, which remains an organization authority. The project-wide singletons — brand, default locale, logo and recipient copy — are what a live recipient sees, so writing them requires a live credential; a test credential may read them and may write its own environment's policy." }, "ApiCredentialScopeSet": { "type": "array", "minItems": 1, "maxItems": 11, "uniqueItems": true, "items": { "$ref": "#/components/schemas/ApiCredentialScope" } }, "ApiCredentialSecret": { "type": "string", "pattern": "^wb_pc1\\.pcred_[A-Za-z0-9_-]{21}[AQgw]\\.[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$", "description": "The exact one-time runtime bearer syntax. The final segment is canonical unpadded base64url for exactly 32 random secret bytes." }, "Channel": { "type": "string", "enum": ["telegram", "slack", "email"], "description": "A provider-neutral delivery channel. Adding a member makes it representable; it does not claim that every deployment has registered an executable adapter." }, "EmailAddress": { "type": "string", "minLength": 3, "maxLength": 254, "pattern": "^(?=[^@]{1,64}@)(?!\\.)(?![^@]*\\.@)(?![^@]*\\.\\.)[A-Za-z0-9!#$%&'*+/=?^_`{|}~.-]+@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$", "description": "Exactly one mailbox: an unquoted ASCII dot-atom local part plus a canonical lower-case IDNA domain. The comparison key preserves local-part bytes and case and lower-cases only the domain; dot, plus-tag, alias and provider equivalence are never inferred." }, "ConnectionIdentity": { "type": "object", "description": "The identity a subscriber will see, named the way its provider names it. Carries the provider so a reader knows what kind of handle it is holding, rather than inferring it from the field's name. One shape for every provider: what differs between them is the handle's own format, which is stated here as a rule rather than as a separate type per provider.", "required": ["provider", "handle"], "properties": { "provider": { "$ref": "#/components/schemas/ChannelConnectionProvider" }, "handle": { "type": "string", "minLength": 1, "description": "The visible provider handle without a provider-specific sigil — a bot username, a workspace or app display name, a sender address. Never a credential, installation identifier or provider-native identity reference." } }, "allOf": [ { "if": { "properties": { "provider": { "const": "email" } }, "required": ["provider"] }, "then": { "properties": { "handle": { "$ref": "#/components/schemas/EmailAddress" } } }, "else": { "properties": { "handle": { "type": "string", "maxLength": 128 } } } } ], "additionalProperties": false }, "ClassifiedError": { "type": "object", "description": "A stable, safe error classification with no provider response or credential material.", "required": ["code", "retryable"], "properties": { "code": { "$ref": "#/components/schemas/ProblemCode" }, "retryable": { "type": "boolean" }, "detail": { "type": "string", "minLength": 1, "maxLength": 1024 }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" } }, "additionalProperties": false }, "EmailVerificationSummary": { "type": "object", "required": ["status", "masked_address", "expires_at"], "properties": { "status": { "enum": ["pending", "verified", "failed", "expired"] }, "masked_address": { "type": "string", "minLength": 3, "maxLength": 254, "description": "Masked recipient address. Never the full mailbox." }, "expires_at": { "$ref": "#/components/schemas/Timestamp" } }, "additionalProperties": false }, "MessageTarget": { "type": "object", "required": ["subscriber_id"], "properties": { "subscriber_id": { "$ref": "#/components/schemas/OpaqueIdentifier" } }, "additionalProperties": false }, "MessageDeliveryTarget": { "type": "string", "enum": ["connection", "simulator"], "description": "The effective provider boundary selected for a message. Connection delivery uses the exact authorized environment connection; simulator delivery never calls a provider." }, "StructuredTextSection": { "type": "object", "required": ["text"], "properties": { "heading": { "description": "An optional semantic heading for this section.", "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 800 }, "text": { "description": "The section body, also represented in the complete fallback text.", "type": "string", "minLength": 1, "maxLength": 1000, "x-max-utf8-bytes": 4000 } }, "additionalProperties": false }, "TextContent": { "type": "object", "required": ["type", "text"], "properties": { "type": { "const": "text" }, "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/NotificationImage" } }, "additionalProperties": false }, "DocumentSectionBlock": { "description": "One prose section in an ordered portable document.", "type": "object", "required": ["type", "text"], "properties": { "type": { "const": "section" }, "heading": { "description": "An optional semantic heading for this section.", "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 800 }, "text": { "description": "The section prose.", "type": "string", "minLength": 1, "maxLength": 1000, "x-max-utf8-bytes": 4000 } }, "additionalProperties": false }, "DocumentFact": { "type": "object", "required": ["label", "value"], "properties": { "label": { "description": "The semantic label for this fact.", "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 800 }, "value": { "description": "The semantic value for this fact.", "type": "string", "minLength": 1, "maxLength": 1000, "x-max-utf8-bytes": 4000 } }, "additionalProperties": false }, "DocumentFactsBlock": { "description": "One ordered group of semantic label/value facts.", "type": "object", "required": ["type", "items"], "properties": { "type": { "const": "facts" }, "items": { "type": "array", "minItems": 1, "maxItems": 24, "items": { "$ref": "#/components/schemas/DocumentFact" } } }, "additionalProperties": false }, "DocumentTableCell": { "type": "string", "minLength": 1, "maxLength": 500, "x-max-utf8-bytes": 2000 }, "DocumentTableRow": { "type": "array", "minItems": 2, "maxItems": 8, "items": { "$ref": "#/components/schemas/DocumentTableCell" } }, "DocumentTableBlock": { "description": "One small semantic table. Every row must have exactly one cell for each column.", "type": "object", "required": ["type", "heading", "columns", "rows"], "properties": { "type": { "const": "table" }, "heading": { "description": "The semantic heading for this table.", "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 800 }, "columns": { "description": "The ordered column headings.", "type": "array", "minItems": 2, "maxItems": 8, "items": { "$ref": "#/components/schemas/DocumentTableCell" } }, "rows": { "description": "The ordered table rows.", "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/DocumentTableRow" } } }, "x-rows-match-columns": true, "additionalProperties": false }, "DocumentDetailsBlock": { "description": "One supporting disclosure in an ordered portable document.", "type": "object", "required": ["type", "summary", "text"], "properties": { "type": { "const": "details" }, "summary": { "description": "The always-visible semantic summary.", "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 800 }, "text": { "description": "The supporting prose.", "type": "string", "minLength": 1, "maxLength": 2000, "x-max-utf8-bytes": 8000 } }, "additionalProperties": false }, "DocumentBlock": { "oneOf": [ { "$ref": "#/components/schemas/DocumentSectionBlock" }, { "$ref": "#/components/schemas/DocumentFactsBlock" }, { "$ref": "#/components/schemas/DocumentTableBlock" }, { "$ref": "#/components/schemas/DocumentDetailsBlock" } ] }, "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" } ] }, "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 }, "InteractionPrompt": { "type": "string", "minLength": 1, "maxLength": 1000 }, "Timestamp-2": { "type": "string", "format": "date-time", "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])T(?:[01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](?:\\.[0-9]+)?(?:Z|[+-](?:[01][0-9]|2[0-3]):[0-5][0-9])$" }, "InteractionCorrelationId": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[^\\u0000-\\u001F\\u007F]+$", "description": "Caller-owned opaque correlation returned as data, never treated as execution authority." }, "ConfirmInteractionRequest": { "type": "object", "required": ["type", "prompt", "expires_at"], "properties": { "type": { "const": "confirm" }, "prompt": { "$ref": "#/components/schemas/InteractionPrompt" }, "confirm_label": { "type": "string", "minLength": 1, "maxLength": 40 }, "deny_label": { "type": "string", "minLength": 1, "maxLength": 40 }, "expires_at": { "$ref": "#/components/schemas/Timestamp-2", "description": "Must be 30 seconds through 24 hours after server acceptance." }, "correlation_id": { "$ref": "#/components/schemas/InteractionCorrelationId" } }, "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"], "properties": { "type": { "const": "select" }, "prompt": { "$ref": "#/components/schemas/InteractionPrompt" }, "options": { "type": "array", "minItems": 2, "maxItems": 6, "items": { "$ref": "#/components/schemas/InteractionOption" }, "x-unique-property": "value" }, "expires_at": { "$ref": "#/components/schemas/Timestamp-2", "description": "Must be 30 seconds through 24 hours after server acceptance." }, "correlation_id": { "$ref": "#/components/schemas/InteractionCorrelationId" } }, "additionalProperties": false }, "InputInteractionRequest": { "type": "object", "required": ["type", "prompt", "expires_at"], "properties": { "type": { "const": "input" }, "prompt": { "$ref": "#/components/schemas/InteractionPrompt" }, "expires_at": { "$ref": "#/components/schemas/Timestamp-2", "description": "Must be 30 seconds through 24 hours after server acceptance." }, "correlation_id": { "$ref": "#/components/schemas/InteractionCorrelationId" } }, "additionalProperties": false }, "HighestProvenProviderState": { "type": "string", "enum": ["none", "provider_accepted"], "description": "The strongest provider assertion the service can prove; it is not an end-device delivery receipt." }, "BroadcastMessageProvenance": { "type": "object", "description": "Provenance carried by an ordinary message created during group expansion. The broadcast, message subscriber_id, and exact historical membership generation form the child uniqueness boundary.", "required": ["broadcast_id", "group_id", "membership_generation"], "properties": { "broadcast_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "group_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "membership_generation": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "MessageState": { "type": "string", "enum": [ "accepted", "dispatch_pending", "queued", "sending", "provider_accepted", "retry_wait", "terminal_failed", "outcome_unknown", "cancelled", "expired" ] }, "TrimmedInputAnswer": { "type": "string", "minLength": 1, "maxLength": 4000, "pattern": "^\\S(?:[\\s\\S]*\\S)?$", "description": "Untrusted input text after leading and trailing whitespace is removed." }, "OpaqueIdentifier-2": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\u0000-\\u001F\\u007F]+$", "description": "An opaque identifier whose internal encoding is not a public promise." }, "InteractionState": { "type": "string", "enum": ["open", "answered", "expired", "cancelled", "retired"] }, "OpaqueIdentifier-3": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\u0000-\\u001F\\u007F]+$" }, "Environment-2": { "type": "string", "enum": ["test", "live"] }, "MachineScope": { "type": "string", "enum": [ "machine-messages:write", "machine-messages:read", "machine-events:read", "machine-events:ack" ] }, "MachineScopeSummary": { "type": "array", "items": { "$ref": "#/components/schemas/MachineScope" }, "minItems": 4, "maxItems": 4, "uniqueItems": true, "description": "Fixed least-privilege capabilities, each constrained to this client's bound destination or stream." }, "MachineSecretDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$", "description": "The only secret-derived value accepted by the administration API." }, "ConfirmInteractionResponse": { "type": "object", "required": ["type", "value"], "properties": { "type": { "const": "confirm" }, "value": { "type": "boolean" } }, "additionalProperties": false }, "SelectInteractionResponse": { "type": "object", "required": ["type", "value"], "properties": { "type": { "const": "select" }, "value": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\u0000-\\u001F\\u007F]+$" } }, "additionalProperties": false }, "InputInteractionResponse": { "type": "object", "required": ["type", "value"], "properties": { "type": { "const": "input" }, "value": { "$ref": "#/components/schemas/TrimmedInputAnswer" } }, "additionalProperties": false }, "InteractionResponse": { "oneOf": [ { "$ref": "#/components/schemas/ConfirmInteractionResponse" }, { "$ref": "#/components/schemas/SelectInteractionResponse" }, { "$ref": "#/components/schemas/InputInteractionResponse" } ] }, "SafeChannelContext": { "type": "object", "required": ["binding_id", "channel", "conversation_kind"], "properties": { "binding_id": { "$ref": "#/components/schemas/OpaqueIdentifier-2" }, "channel": { "type": "string", "enum": ["telegram"], "description": "Which channel the person answered on. An enum rather than a fixed value, so that a second channel adds a member instead of changing the type every generated client holds. The vocabulary grows additively; a consumer that meets a member it does not know should treat the answer as valid and the channel as unfamiliar rather than refusing it." }, "conversation_kind": { "type": "string", "enum": ["private_chat", "thread", "group"] }, "display_name": { "type": "string", "minLength": 1, "maxLength": 120 } }, "additionalProperties": false }, "QuarantineReasonCode": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9][a-z0-9._-]*$" }, "MachineEventAckDisposition": { "type": "string", "enum": ["processed", "quarantined"] }, "CustomerEndpointStatus": { "type": "string", "enum": ["unverified", "active", "paused", "disabled"] }, "CustomerEventType": { "type": "string", "enum": [ "subscription.activated", "subscription.revoked", "message.provider_accepted", "message.delivered", "message.failed", "message.expired", "interaction.received", "interaction.expired", "agent_binding.degraded", "subscription.asserted", "subscription.asserted_revoked" ] }, "CustomerEndpointFailure": { "type": "object", "required": ["at", "category"], "properties": { "at": { "$ref": "#/components/schemas/Timestamp" }, "category": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9_]+$" } }, "additionalProperties": false }, "CustomerEndpointSecret": { "type": "string", "pattern": "^whsec_[A-Za-z0-9+/]{43}=$", "description": "Exactly 32 random bytes in the Standard Webhooks secret format. Returned only by the first successful create or rotate response." }, "CustomerEndpointAttemptDiagnostic": { "type": "object", "description": "Content-free per-attempt timing and failure classification.", "required": ["id", "event_id", "attempt", "status", "created_at"], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "event_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "attempt": { "type": "integer", "minimum": 1, "maximum": 8 }, "status": { "type": "string", "enum": [ "pending", "attempting", "delivered", "retry_wait", "terminal_failed", "paused" ] }, "diagnostic_code": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9_]+$" }, "http_status": { "type": "integer", "minimum": 100, "maximum": 599 }, "started_at": { "$ref": "#/components/schemas/Timestamp" }, "completed_at": { "$ref": "#/components/schemas/Timestamp" }, "created_at": { "$ref": "#/components/schemas/Timestamp" } }, "additionalProperties": false }, "ChannelConnectionSetupStatus": { "type": "string", "enum": [ "awaiting_handoff", "awaiting_creation", "provisioning", "failed", "expired" ], "description": "How far a guided setup has reached, which is the only thing a caller can act on while a connection is still `pending`. `awaiting_handoff` waits for the administrator to open the link on the Telegram account that will own the bot; `awaiting_creation` means that Telegram account is bound and the bot does not exist yet; `provisioning` means the bot exists and WhooshBang is installing delivery on it. `failed` and `expired` end the attempt without ending the connection — another attempt can be started on the same `pending` connection — and neither withdraws a bot Telegram has already created, because no provider API can delete one." }, "SuggestedBotUsername": { "type": "string", "minLength": 5, "maxLength": 32, "pattern": "^[A-Za-z][A-Za-z0-9_]{1,28}[Bb][Oo][Tt]$", "description": "The @username Telegram's own creation dialog is prefilled with, constrained to Telegram's own rule: 5 to 32 characters, a letter first, letters, digits, and underscores after it, ending in `bot` in any case. The caller proposes it because it is the handle every subscriber sees forever and it cannot be changed once the bot exists — a WhooshBang-generated handle would permanently brand a customer's own bot with our naming, which is the one thing customer-owned modes exist to prevent. It is a suggestion and not a reservation: the administrator can type a different handle into Telegram's dialog, which validates the shape and refuses a handle somebody already holds." }, "ChannelConnectionSetup": { "type": "object", "description": "The unfinished half of a customer-managed connection: what the administrator still has to do, and by when. It is deliberately incapable of carrying a secret. The new bot's token travels from Telegram to WhooshBang server to server, so nothing here is credential material and nothing here references any — which is what makes this object safe to poll, render in a dashboard, or hand to whoever is doing the setup.", "required": [ "status", "handoff_url", "expires_at", "suggested_bot_username" ], "properties": { "status": { "$ref": "#/components/schemas/ChannelConnectionSetupStatus" }, "handoff_url": { "type": "string", "format": "uri", "pattern": "^https://[^\\s]+$", "maxLength": 2048, "description": "The link the administrator opens to put their own Telegram account behind this setup; for Telegram it is `https://t.me/?start=`. It is a capability for exactly one setup session and nothing else: it names no organization, no project, and no environment, it stops working at `expires_at`, and only the first Telegram account to open it is bound. It is not credential material, so displaying it costs nothing beyond letting whoever sees it first become the owner of the bot this setup creates. After `expired` or `failed` it binds nothing, and restarting the setup issues a new one rather than reviving this." }, "expires_at": { "$ref": "#/components/schemas/Timestamp", "description": "When an unfinished setup stops being usable. The window is short on purpose: an unopened link is an outstanding invitation to own a bot in this environment, and a caller who lets it lapse restarts rather than inherits." }, "suggested_bot_username": { "$ref": "#/components/schemas/SuggestedBotUsername", "description": "The suggestion this attempt was started with, echoed so a caller can show the administrator what Telegram will prefill. It records what was asked for and never what exists: the administrator may override it in Telegram's dialog, and `identity` on the connection is the only description of the bot that was actually created." }, "failure_reason": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Why this attempt ended, in terms the administrator can act on. Absent when there is nothing both safe and useful to say: an attempt refused because that Telegram account already holds a live setup says only that, because naming the organization, project, or environment holding the other one would disclose another customer." } }, "additionalProperties": false }, "TelegramChannelConnection": { "type": "object", "description": "An existing Telegram connection. Its public shape remains unchanged.", "required": [ "id", "project_id", "environment_id", "environment", "provider", "mode", "display_name", "status", "health", "row_version", "created_at", "updated_at", "diagnostic_id" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment": { "$ref": "#/components/schemas/Environment" }, "provider": { "const": "telegram" }, "mode": { "enum": ["whooshbang_shared", "customer_managed", "customer_byok"] }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "status": { "$ref": "#/components/schemas/ChannelConnectionStatus" }, "health": { "$ref": "#/components/schemas/ProviderHealthState" }, "identity": { "$ref": "#/components/schemas/ConnectionIdentity" }, "setup": { "$ref": "#/components/schemas/ChannelConnectionSetup" }, "authorization_setup": false, "app_setup": false, "installation": false, "row_version": { "type": "integer", "minimum": 1, "description": "Send this back on an update. A stale value is refused rather than silently overwriting a change made in between." }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "archived_at": { "$ref": "#/components/schemas/Timestamp" }, "health_checked_at": { "$ref": "#/components/schemas/Timestamp" }, "last_transition_at": { "$ref": "#/components/schemas/Timestamp" }, "last_transition_reason": { "type": "string", "minLength": 1, "maxLength": 200 }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" } }, "additionalProperties": false }, "HostedConnectionCapability": { "type": "string", "enum": ["send_messages"], "description": "A safe capability granted to this exact hosted connection. It is product vocabulary, never a raw provider scope." }, "ProviderInstallationSummary": { "type": "object", "description": "A safe summary projected only through an exact authorized connection. Internal installation ids, provider-native workspace ids, scope arrays, grant metadata and credentials are absent.", "required": ["display_name", "status", "health"], "properties": { "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "status": { "$ref": "#/components/schemas/ProviderInstallationStatus" }, "health": { "$ref": "#/components/schemas/ProviderHealthState" } }, "additionalProperties": false }, "HostedConnectionRecoveryAction": { "type": "string", "enum": [ "none", "complete_authorization", "wait_for_admin_approval", "retry_authorization", "reinstall", "retry_later", "contact_support" ], "description": "The exact safe next action for the current hosted lifecycle state. Provider wire errors and secret material never occupy this field." }, "HostedChannelConnection": { "type": "object", "description": "A WhooshBang-owned application installed at one provider authority — a workspace, a tenant, a server — and referenced by one exact environment connection.", "required": [ "id", "project_id", "environment_id", "environment", "provider", "mode", "display_name", "status", "health", "capabilities", "recovery_action", "row_version", "created_at", "updated_at", "diagnostic_id" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment": { "$ref": "#/components/schemas/Environment" }, "provider": { "$ref": "#/components/schemas/ChannelConnectionProvider" }, "mode": { "const": "whooshbang_hosted" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "status": { "$ref": "#/components/schemas/ChannelConnectionStatus" }, "health": { "$ref": "#/components/schemas/ProviderHealthState" }, "capabilities": { "type": "array", "maxItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/HostedConnectionCapability" } }, "identity": { "$ref": "#/components/schemas/ConnectionIdentity" }, "setup": false, "app_setup": false, "authorization_setup": { "$ref": "#/components/schemas/ProviderAuthorizationSetup", "description": "The additive hosted authorization state. Older tolerant readers discard this unknown field rather than interpreting it as Telegram setup." }, "installation": { "$ref": "#/components/schemas/ProviderInstallationSummary", "description": "The safe installation authorized for this exact connection. It is never caller-selectable and exposes no provider-native identifier or credential reference." }, "management_url": { "type": "string", "format": "uri", "pattern": "^(?!(?:javascript|data|vbscript|file|blob):)[a-z][a-z0-9+.-]*:[^\\s]+$", "maxLength": 2048, "description": "A provider-owned link that opens this application where the provider's own client presents it, for the exact authorized authority and WhooshBang application. It may use the provider's own URI scheme, never a scheme a browser would execute or read locally. It is not a caller-supplied return URL." }, "recovery_action": { "$ref": "#/components/schemas/HostedConnectionRecoveryAction" }, "last_successful_verification_at": { "$ref": "#/components/schemas/Timestamp" }, "last_successful_delivery_at": { "$ref": "#/components/schemas/Timestamp" }, "row_version": { "type": "integer", "minimum": 1, "description": "Send this back on an update. A stale value is refused rather than silently overwriting a change made in between." }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "archived_at": { "$ref": "#/components/schemas/Timestamp" }, "health_checked_at": { "$ref": "#/components/schemas/Timestamp" }, "last_transition_at": { "$ref": "#/components/schemas/Timestamp" }, "last_transition_reason": { "type": "string", "minLength": 1, "maxLength": 200 }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" } }, "additionalProperties": false }, "CustomerApplicationSetupStatus": { "type": "string", "enum": [ "awaiting_app_creation", "awaiting_authorities", "awaiting_authorization", "awaiting_ingress_proof", "provisioning", "failed", "expired" ], "description": "How far the setup of an application the customer creates and owns has reached, which is the only thing a caller can act on while the connection is still `pending`. Each verification state names a different authority, because a provider may hand an application's secrets over together but exercise them at different moments: `awaiting_authorization` has the authorities and is waiting for the install, `awaiting_ingress_proof` has an installation the provider confirmed and is waiting for the first request the provider itself signs. Collapsing them would let a connection report a verified ingress it has never verified." }, "CustomerApplicationAuthority": { "type": "string", "enum": [ "application_identity", "application_secret", "ingress_secret" ], "description": "One application-specific authority the owner hands over, named for what it is for rather than for what one provider's console calls it. `application_identity` identifies the application and is safe metadata; `application_secret` is what the application authenticates with; `ingress_secret` is what proves an inbound request came from the provider. The last two are write-only, and none of them is ever a value here." }, "CustomerApplicationConnectionSetup": { "type": "object", "description": "The unfinished half of a connection through an application the customer creates and owns: what the owner still has to do at the provider, and by when.\n\nIt is deliberately incapable of carrying a secret. The creation link contains configuration and nothing else, the secrets the owner supplies are write-only and have no field here or on the connection, and the installation grant never travels through a browser at all — WhooshBang obtains it from the provider's own installation exchange. Everything here is therefore safe to poll, render, and hand to whoever is doing the setup.", "required": [ "status", "creation_url", "expires_at", "app_name", "bot_display_name", "outstanding_authorities" ], "properties": { "status": { "$ref": "#/components/schemas/CustomerApplicationSetupStatus" }, "creation_url": { "type": "string", "format": "uri", "pattern": "^https://[^\\s]+$", "maxLength": 8192, "description": "The provider's own application-creation flow, opened with this application's configuration already filled in where the provider allows it, so the owner reviews and confirms rather than writing configuration by hand. The URL carries configuration only: it names no organization, project, or environment and contains no credential. Any opaque handle it carries selects candidate setup state and authorizes nothing." }, "expires_at": { "$ref": "#/components/schemas/Timestamp", "description": "When an unfinished setup stops being usable. A setup that already produced an application stays recoverable past this, because the application exists whether or not the browser came back." }, "authorization_url": { "type": "string", "format": "uri", "pattern": "^https://[^\\s]+$", "maxLength": 2048, "description": "The short-lived handoff that installs the owner's application, present once its authorities have arrived and an installation has been started. It carries opaque state, never a provider credential or a raw authorization code, and the grant it produces is returned to WhooshBang by the provider rather than to the browser." }, "app_name": { "type": "string", "minLength": 1, "maxLength": 35, "description": "The name the owner chose, echoed so a resumed session shows the same application it started with." }, "bot_display_name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The bot display name the owner chose, echoed for the same reason." }, "outstanding_authorities": { "type": "array", "maxItems": 3, "uniqueItems": true, "items": { "$ref": "#/components/schemas/CustomerApplicationAuthority" }, "description": "Which application-specific values this setup is still waiting for. Empty once they have all arrived; it never says what any of them are." }, "failure_reason": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Why this attempt ended, in terms the owner can act on. It never echoes a submitted secret, whole or in part, and never names another customer: an application already connected elsewhere says only that." } }, "additionalProperties": false }, "CustomerApplicationChannelConnection": { "type": "object", "description": "An application the customer created and owns at the provider, referenced by one exact environment connection.\n\nIt differs from the hosted arm in who owns the application and its lifecycle, not in what a notification can do. WhooshBang custodies the application-specific authorities the provider makes unavoidable and none of them appears here or in any other read: absence, not redaction, is the mechanism.", "required": [ "id", "project_id", "environment_id", "environment", "provider", "mode", "display_name", "status", "health", "capabilities", "recovery_action", "row_version", "created_at", "updated_at", "diagnostic_id" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment": { "$ref": "#/components/schemas/Environment" }, "provider": { "$ref": "#/components/schemas/ChannelConnectionProvider" }, "mode": { "const": "customer_managed" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "status": { "$ref": "#/components/schemas/ChannelConnectionStatus" }, "health": { "$ref": "#/components/schemas/ProviderHealthState" }, "capabilities": { "type": "array", "maxItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/HostedConnectionCapability" } }, "identity": { "$ref": "#/components/schemas/ConnectionIdentity" }, "setup": false, "authorization_setup": false, "app_setup": { "$ref": "#/components/schemas/CustomerApplicationConnectionSetup", "description": "The guided customer-owned setup state. A distinct field from Telegram's `setup` and the hosted arm's `authorization_setup` so a tolerant reader can never mistake one journey's progress for another's." }, "installation": { "$ref": "#/components/schemas/ProviderInstallationSummary", "description": "The safe installation this exact connection owns. It exposes no provider-native identifier and no credential reference." }, "management_url": { "type": "string", "format": "uri", "pattern": "^(?!(?:javascript|data|vbscript|file|blob):)[a-z][a-z0-9+.-]*:[^\\s]+$", "maxLength": 2048, "description": "A provider-owned link that opens the customer's own application where the provider's own client presents it, at the authority it is installed at. It may use the provider's own URI scheme, never a scheme a browser would execute or read locally. It is not a caller-supplied return URL." }, "recovery_action": { "$ref": "#/components/schemas/HostedConnectionRecoveryAction" }, "last_successful_verification_at": { "$ref": "#/components/schemas/Timestamp" }, "last_successful_delivery_at": { "$ref": "#/components/schemas/Timestamp" }, "row_version": { "type": "integer", "minimum": 1, "description": "Send this back on an update. A stale value is refused rather than silently overwriting a change made in between." }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "archived_at": { "$ref": "#/components/schemas/Timestamp" }, "health_checked_at": { "$ref": "#/components/schemas/Timestamp" }, "last_transition_at": { "$ref": "#/components/schemas/Timestamp" }, "last_transition_reason": { "type": "string", "minLength": 1, "maxLength": 200 }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" } }, "additionalProperties": false }, "SharedEmailStatus": { "type": "object", "description": "Safe state of the exact shared sender generation and this organization’s domain hold. It conveys no recipient consent and never authorizes fallback.", "required": [ "sender_generation", "sender_state", "hold", "recovery_action" ], "properties": { "sender_generation": { "type": "integer", "minimum": 1 }, "sender_state": { "enum": ["active", "draining", "held", "retired"] }, "hold": { "enum": ["clear", "held"] }, "recovery_action": { "enum": [ "none", "resume_connection", "acknowledge_remediation", "retry_later" ] }, "policy_version": { "type": "integer", "minimum": 1 }, "held_at": { "$ref": "#/components/schemas/Timestamp" } }, "additionalProperties": false }, "EmailLocalPart": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^(?!\\.)(?!.*\\.$)(?!.*\\.\\.)[A-Za-z0-9!#$%&'*+/=?^_`{|}~.-]+$", "description": "One unquoted ASCII dot-atom local part. Its bytes and case are preserved exactly; quoted and SMTPUTF8 local parts are unsupported." }, "EmailDisplayName": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[^\u0000-\u001f-Ÿ

]+$", "description": "A sender display name without control characters. It is encoded safely as a structured address field and never accepted as a raw header." }, "EmailChannelConnection": { "description": "An email connection in one exact project environment. Provider authority and resource identifiers are represented only by organization-scoped WhooshBang ids; credentials and provider-native ids are structurally absent.", "oneOf": [ { "type": "object", "required": [ "id", "project_id", "environment_id", "environment", "provider", "mode", "display_name", "shared_identity_id", "status", "health", "delivery_policy", "row_version", "created_at", "updated_at", "diagnostic_id" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment": { "$ref": "#/components/schemas/Environment" }, "provider": { "const": "email" }, "mode": { "const": "whooshbang_shared" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "shared_identity_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "status": { "$ref": "#/components/schemas/ChannelConnectionStatus" }, "health": { "$ref": "#/components/schemas/ProviderHealthState" }, "setup": false, "app_setup": false, "authorization_setup": false, "installation": false, "domain_id": false, "sender_local_part": false, "sender_display_name": false, "delivery_policy": { "$ref": "#/components/schemas/EmailDeliveryPolicy" }, "identity": { "$ref": "#/components/schemas/ConnectionIdentity" }, "health_checked_at": { "$ref": "#/components/schemas/Timestamp" }, "last_transition_at": { "$ref": "#/components/schemas/Timestamp" }, "last_transition_reason": { "type": "string", "minLength": 1, "maxLength": 200 }, "row_version": { "type": "integer", "minimum": 1 }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "archived_at": { "$ref": "#/components/schemas/Timestamp" }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" }, "email_status": { "$ref": "#/components/schemas/SharedEmailStatus" } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "project_id", "environment_id", "environment", "provider", "mode", "display_name", "status", "health", "installation", "domain_id", "sender_local_part", "sender_display_name", "delivery_policy", "row_version", "created_at", "updated_at", "diagnostic_id" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "environment": { "$ref": "#/components/schemas/Environment" }, "provider": { "const": "email" }, "mode": { "const": "customer_managed" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "status": { "$ref": "#/components/schemas/ChannelConnectionStatus" }, "health": { "$ref": "#/components/schemas/ProviderHealthState" }, "shared_identity_id": false, "setup": false, "app_setup": false, "authorization_setup": { "$ref": "#/components/schemas/ProviderAuthorizationSetup" }, "installation": { "$ref": "#/components/schemas/ProviderInstallationSummary" }, "domain_id": { "$ref": "#/components/schemas/OpaqueIdentifier", "description": "The organization-owned domain authorized to this connection. It is resolved under the authenticated organization and cannot select another tenant's resource; another connection may hold its own authorization edge to the same domain." }, "sender_local_part": { "$ref": "#/components/schemas/EmailLocalPart" }, "sender_display_name": { "$ref": "#/components/schemas/EmailDisplayName" }, "delivery_policy": { "$ref": "#/components/schemas/EmailDeliveryPolicy", "description": "A read-only projection of the authorized domain's delivery policy. The domain is the sole mutation authority for TLS." }, "identity": { "$ref": "#/components/schemas/ConnectionIdentity" }, "health_checked_at": { "$ref": "#/components/schemas/Timestamp" }, "last_transition_at": { "$ref": "#/components/schemas/Timestamp" }, "last_transition_reason": { "type": "string", "minLength": 1, "maxLength": 200 }, "row_version": { "type": "integer", "minimum": 1 }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "archived_at": { "$ref": "#/components/schemas/Timestamp" }, "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" } }, "additionalProperties": false } ] }, "RecipientBrand": { "type": "object", "description": "Constrained recipient-facing brand tokens. Arbitrary markup, CSS, scripts, remote assets, fonts, and tracking inputs are structurally absent.", "required": ["display_name", "accent_color", "color_scheme"], "properties": { "display_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "logo_asset_id": { "$ref": "#/components/schemas/RecipientBrandAssetId", "description": "A normalized asset already hosted by WhooshBang, never a caller-supplied URL." }, "accent_color": { "type": "string", "pattern": "^#[0-9A-F]{6}$" }, "color_scheme": { "type": "string", "enum": ["light", "dark", "system"] } }, "additionalProperties": false }, "ExactOrigin": { "type": "string", "format": "uri", "minLength": 8, "maxLength": 255, "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 recipient groups." }, "RegisteredReturnUrl": { "type": "string", "format": "uri", "minLength": 8, "maxLength": 2048, "pattern": "^https?://[^\\s{}]+$", "description": "An exact registered return destination. Templates, credentials, and fragments are forbidden; HTTP is accepted only for localhost or synthetic .test configuration." }, "ReturnDestination": { "type": "object", "required": ["key", "url"], "properties": { "key": { "$ref": "#/components/schemas/DeveloperKey" }, "url": { "$ref": "#/components/schemas/RegisteredReturnUrl" } }, "additionalProperties": false }, "EmailBindingConsent": { "description": "How consent for this exact subscriber, notifier and connection was established. A customer assertion never becomes recipient-observed verification. Complaint, unsubscribe and suppression override either arm.", "oneOf": [ { "type": "object", "required": ["kind", "observed_at"], "properties": { "kind": { "const": "recipient_observed" }, "observed_at": { "$ref": "#/components/schemas/Timestamp" } }, "additionalProperties": false }, { "type": "object", "required": ["kind", "consented_at", "source"], "properties": { "kind": { "const": "asserted_prior_consent" }, "consented_at": { "$ref": "#/components/schemas/Timestamp" }, "source": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[^\u0000-\u001f-Ÿ

]+$", "description": "A bounded customer description of where consent was collected. The authenticated asserting actor is recorded by the service, never accepted from this object." }, "asserted_at": { "$ref": "#/components/schemas/Timestamp" }, "asserted_by": { "type": "object", "required": ["kind", "id"], "properties": { "kind": { "enum": ["credential", "grant", "session"] }, "id": { "$ref": "#/components/schemas/OpaqueIdentifier" } }, "additionalProperties": false }, "domain_id": { "$ref": "#/components/schemas/OpaqueIdentifier" } }, "additionalProperties": false } ] }, "RecipientChannelSummary": { "type": "object", "description": "Safe state for one configured channel. Provider identities, credentials, callback state, and other subscribers are absent.", "required": ["channel", "state", "preferred"], "properties": { "channel": { "$ref": "#/components/schemas/Channel" }, "state": { "type": "string", "enum": ["available", "connected", "paused"] }, "binding_id": { "$ref": "#/components/schemas/OpaqueIdentifier", "description": "The exact binding owned by this session's subscriber. Present only for connected or paused state." }, "preferred": { "type": "boolean" }, "connection_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "masked_address": { "type": "string", "minLength": 3, "maxLength": 254, "description": "Masked recipient address. Never the full mailbox." }, "consent": { "$ref": "#/components/schemas/EmailBindingConsent" } }, "allOf": [ { "if": { "properties": { "state": { "enum": ["connected", "paused"] } }, "required": ["state"] }, "then": { "required": ["binding_id"], "properties": { "binding_id": {} } } }, { "if": { "properties": { "state": { "const": "available" } }, "required": ["state"] }, "then": { "properties": { "binding_id": false, "preferred": { "const": false } } } } ], "additionalProperties": false }, "RecipientSessionCapabilityPrefix": { "type": "string", "minLength": 33, "maxLength": 33, "pattern": "^wb_rs1\\.rsc_[A-Za-z0-9_-]{22}$", "description": "A non-secret prefix safe for later session projection and support correlation." }, "RecipientSessionOperation": { "type": "string", "enum": [ "session:read", "handoff:create", "binding:pause", "binding:resume", "binding:revoke", "preference:write" ] }, "RecipientSessionCapability": { "type": "string", "minLength": 77, "maxLength": 77, "pattern": "^wb_rs1\\.rsc_[A-Za-z0-9_-]{22}\\.[A-Za-z0-9_-]{43}$", "writeOnly": true, "description": "Creation-only opaque recipient capability. It is stored by digest and is never accepted as an application bearer credential." }, "ProviderHandoffCompletionMode": { "oneOf": [ { "type": "object", "required": ["mode", "target_origin", "opener_nonce"], "properties": { "mode": { "const": "popup" }, "target_origin": { "$ref": "#/components/schemas/ExactOrigin" }, "opener_nonce": { "type": "string", "minLength": 22, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" } }, "additionalProperties": false }, { "type": "object", "required": ["mode"], "properties": { "mode": { "const": "redirect" } }, "additionalProperties": false } ] }, "TimeZone": { "type": "string", "minLength": 3, "maxLength": 255, "pattern": "^(?:UTC|[A-Za-z][A-Za-z0-9._+-]*(?:/[A-Za-z][A-Za-z0-9._+-]*)+)$", "description": "A named IANA time-zone identifier. Numeric offsets, abbreviations and display labels are invalid; recognized aliases normalize to the runtime's canonical identifier before persistence. Providers may leave it absent." }, "BroadcastAggregate": { "type": "object", "description": "A projection over expansion and ordinary child-message states, not an independent delivery state machine.", "required": [ "audience", "expanded", "pending", "provider_accepted", "delivered", "skipped", "failed", "cancelled", "expired" ], "properties": { "audience": { "type": "integer", "minimum": 0 }, "expanded": { "type": "integer", "minimum": 0 }, "pending": { "type": "integer", "minimum": 0 }, "provider_accepted": { "type": "integer", "minimum": 0 }, "delivered": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "cancelled": { "type": "integer", "minimum": 0 }, "expired": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "SafeExplanation": { "type": "string", "minLength": 1, "maxLength": 500 }, "InteractionCapability": { "type": "object", "required": ["mode"], "properties": { "mode": { "type": "string", "enum": ["native", "fallback", "unsupported", "conditional"] }, "explanation": { "$ref": "#/components/schemas/SafeExplanation" } }, "allOf": [ { "if": { "properties": { "mode": { "enum": ["fallback", "conditional"] } }, "required": ["mode"] }, "then": { "required": ["explanation"], "properties": { "explanation": {} } } } ], "additionalProperties": false }, "ContextSupport": { "type": "object", "required": ["mode"], "properties": { "mode": { "type": "string", "enum": ["supported", "unsupported", "conditional"] }, "explanation": { "$ref": "#/components/schemas/SafeExplanation" } }, "allOf": [ { "if": { "properties": { "mode": { "const": "conditional" } }, "required": ["mode"] }, "then": { "required": ["explanation"], "properties": { "explanation": {} } } } ], "additionalProperties": false }, "Degradation": { "type": "object", "required": ["active"], "properties": { "active": { "type": "boolean" }, "code": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9][a-z0-9._-]*$" }, "explanation": { "$ref": "#/components/schemas/SafeExplanation" } }, "allOf": [ { "if": { "properties": { "active": { "const": true } }, "required": ["active"] }, "then": { "required": ["code", "explanation"], "properties": { "code": {}, "explanation": {} } }, "else": { "properties": { "code": false, "explanation": false } } } ], "additionalProperties": false }, "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": "1.0.0-rc.25", "title": "ProviderCapabilitiesV1", "description": "Provider-neutral, renderer-facing delivery and interaction capabilities with explicit degradation.", "type": "object", "required": [ "schema", "provider", "text", "interaction", "streaming", "edit", "receipts", "contexts", "rate_limit", "degradation" ], "properties": { "schema": { "const": "whooshbang.provider-capabilities.v1" }, "provider": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]*$" }, "text": { "type": "object", "required": ["supported", "maximum_bytes"], "properties": { "supported": { "type": "boolean" }, "maximum_bytes": { "type": "integer", "minimum": 1, "maximum": 1048576 } }, "additionalProperties": false }, "interaction": { "type": "object", "required": ["confirm", "select", "input"], "properties": { "confirm": { "$ref": "#/components/schemas/InteractionCapability" }, "select": { "$ref": "#/components/schemas/InteractionCapability" }, "input": { "$ref": "#/components/schemas/InteractionCapability" } }, "additionalProperties": false }, "streaming": { "type": "object", "required": ["mode"], "properties": { "mode": { "type": "string", "enum": [ "native", "edit", "typing_then_final", "final_only", "unsupported" ] }, "explanation": { "$ref": "#/components/schemas/SafeExplanation" } }, "additionalProperties": false }, "edit": { "type": "object", "required": ["supported"], "properties": { "supported": { "type": "boolean" } }, "additionalProperties": false }, "receipts": { "type": "object", "required": ["provider_accepted", "delivered", "read"], "properties": { "provider_accepted": { "type": "boolean" }, "delivered": { "type": "boolean" }, "read": { "type": "boolean" } }, "additionalProperties": false }, "contexts": { "type": "object", "required": ["private_chat", "thread", "group"], "properties": { "private_chat": { "$ref": "#/components/schemas/ContextSupport" }, "thread": { "$ref": "#/components/schemas/ContextSupport" }, "group": { "$ref": "#/components/schemas/ContextSupport" } }, "additionalProperties": false }, "rate_limit": { "type": "object", "required": ["strategy"], "properties": { "strategy": { "type": "string", "enum": [ "provider_retry_after", "token_bucket", "fixed_window", "adaptive", "unknown" ] }, "explanation": { "$ref": "#/components/schemas/SafeExplanation" } }, "additionalProperties": false }, "degradation": { "$ref": "#/components/schemas/Degradation" } }, "$defs": { "SafeExplanation": { "type": "string", "minLength": 1, "maxLength": 500 }, "InteractionCapability": { "type": "object", "required": ["mode"], "properties": { "mode": { "type": "string", "enum": ["native", "fallback", "unsupported", "conditional"] }, "explanation": { "$ref": "#/components/schemas/SafeExplanation" } }, "allOf": [ { "if": { "properties": { "mode": { "enum": ["fallback", "conditional"] } }, "required": ["mode"] }, "then": { "required": ["explanation"], "properties": { "explanation": {} } } } ], "additionalProperties": false }, "ContextSupport": { "type": "object", "required": ["mode"], "properties": { "mode": { "type": "string", "enum": ["supported", "unsupported", "conditional"] }, "explanation": { "$ref": "#/components/schemas/SafeExplanation" } }, "allOf": [ { "if": { "properties": { "mode": { "const": "conditional" } }, "required": ["mode"] }, "then": { "required": ["explanation"], "properties": { "explanation": {} } } } ], "additionalProperties": false }, "Degradation": { "type": "object", "required": ["active"], "properties": { "active": { "type": "boolean" }, "code": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9][a-z0-9._-]*$" }, "explanation": { "$ref": "#/components/schemas/SafeExplanation" } }, "allOf": [ { "if": { "properties": { "active": { "const": true } }, "required": ["active"] }, "then": { "required": ["code", "explanation"], "properties": { "code": {}, "explanation": {} } }, "else": { "properties": { "code": false, "explanation": false } } } ], "additionalProperties": false } }, "additionalProperties": false }, "SubscriberDataExportRecord": { "type": "object", "description": "One semantic record held about the subscriber. The source names the durable store or recovered semantic value; data contains plaintext business fields and excludes custody metadata and secrets.", "required": ["source", "data"], "properties": { "source": { "type": "string", "minLength": 1, "maxLength": 96, "pattern": "^[a-z][a-z0-9_.-]*$" }, "data": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "SubscriberDataExportExcludedControllerData": { "type": "object", "description": "A category deliberately outside the customer-controller artifact because WhooshBang is controller for it.", "required": ["category", "controller", "access"], "properties": { "category": { "type": "string", "enum": ["consent_lifecycle_audit", "service_logs"] }, "controller": { "type": "string", "const": "whooshbang" }, "access": { "type": "string", "const": "separate_recipient_request_required" } }, "additionalProperties": false }, "EmailBindingImportRow": { "type": "object", "required": ["subscriber_id", "notifier_id", "address", "consent"], "properties": { "subscriber_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "notifier_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }, "address": { "$ref": "#/components/schemas/EmailAddress" }, "consent": { "$ref": "#/components/schemas/EmailBindingConsent" } }, "additionalProperties": false } }, "responses": { "BadRequest": { "description": "The request or required idempotency key is invalid.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "requestInvalid": { "value": { "type": "https://whooshbang.flowxo.com/problems/request_invalid", "title": "Request invalid", "status": 400, "detail": "One or more request fields are invalid.", "code": "request_invalid", "diagnostic_id": "diag_request_invalid_001", "retryable": false, "field_errors": [ { "field": "/content/text", "code": "utf8_bytes_exceeded", "detail": "Text must contain at most 8192 UTF-8 bytes." } ] } }, "idempotencyKeyRequired": { "value": { "type": "https://whooshbang.flowxo.com/problems/idempotency_key_required", "title": "Idempotency key required", "status": 400, "detail": "Provide an Idempotency-Key containing 8 to 255 visible ASCII characters.", "code": "idempotency_key_required", "diagnostic_id": "diag_idem_required_001", "retryable": false } } } } } }, "Unauthorized": { "description": "A bearer credential is absent, malformed, invalid, or revoked.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "authenticationRequired": { "value": { "type": "https://whooshbang.flowxo.com/problems/authentication_required", "title": "Authentication required", "status": 401, "detail": "Provide a bearer credential.", "code": "authentication_required", "diagnostic_id": "diag_auth_required_001", "retryable": false } }, "credentialInvalid": { "value": { "type": "https://whooshbang.flowxo.com/problems/credential_invalid", "title": "Credential invalid", "status": 401, "detail": "The bearer credential is malformed, invalid, or revoked.", "code": "credential_invalid", "diagnostic_id": "diag_credential_invalid_001", "retryable": false } } } } } }, "Forbidden": { "description": "The credential lacks scope or cannot address the requested environment.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scopeForbidden": { "value": { "type": "https://whooshbang.flowxo.com/problems/scope_forbidden", "title": "Scope forbidden", "status": 403, "detail": "The credential does not grant the required operation scope.", "code": "scope_forbidden", "diagnostic_id": "diag_scope_forbidden_001", "retryable": false } }, "environmentMismatch": { "value": { "type": "https://whooshbang.flowxo.com/problems/environment_mismatch", "title": "Environment mismatch", "status": 403, "detail": "The credential cannot address a binding in another environment.", "code": "environment_mismatch", "diagnostic_id": "diag_environment_001", "retryable": false } } } } } }, "NotFound": { "description": "The resource is absent or outside the authenticated project/environment.\nThe response never confirms cross-tenant existence.\n", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "resourceNotFound": { "value": { "type": "https://whooshbang.flowxo.com/problems/resource_not_found", "title": "Resource not found", "status": 404, "detail": "The resource was not found.", "code": "resource_not_found", "diagnostic_id": "diag_not_found_001", "retryable": false } }, "resourceExpired": { "value": { "type": "https://whooshbang.flowxo.com/problems/resource_expired", "title": "Resource expired", "status": 404, "detail": "The resource is no longer available.", "code": "resource_expired", "diagnostic_id": "diag_resource_expired_001", "retryable": false } } } } } }, "Conflict": { "description": "An idempotency key, project slug, credential identity, existing\nacknowledgement, or resource state conflicts with the authorized\norganization or request.\n", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "idempotencyConflict": { "value": { "type": "https://whooshbang.flowxo.com/problems/idempotency_conflict", "title": "Idempotency conflict", "status": 409, "detail": "The key was already accepted with materially different validated input.", "code": "idempotency_conflict", "diagnostic_id": "diag_idem_conflict_001", "retryable": false } }, "projectSlugConflict": { "value": { "type": "https://whooshbang.flowxo.com/problems/project_slug_conflict", "title": "Project slug conflict", "status": 409, "detail": "That project slug is already used in this organization.", "code": "project_slug_conflict", "diagnostic_id": "diag_project_slug_conflict_001", "retryable": false, "field_errors": [ { "field": "/slug", "code": "already_exists", "detail": "Choose a different project slug." } ] } }, "replayUnavailable": { "value": { "type": "https://whooshbang.flowxo.com/problems/replay_unavailable", "title": "Replay unavailable", "status": 409, "detail": "Customer event replay is not enabled for this project environment.", "code": "replay_unavailable", "diagnostic_id": "diag_replay_unavailable_rollout_001", "retryable": false, "field_errors": [ { "field": "/", "code": "rollout_disabled", "detail": "Customer event replay is not enabled for this project environment." } ] } } } } } }, "Unprocessable": { "description": "The request is valid in shape but names no usable authorized binding or registered return destination.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "subscriberUnbound": { "value": { "type": "https://whooshbang.flowxo.com/problems/subscriber_unbound", "title": "Subscriber unbound", "status": 422, "detail": "No authorized channel binding is available for this subscriber and notifier.", "code": "subscriber_unbound", "diagnostic_id": "diag_subscriber_unbound_001", "retryable": false } }, "preferredBindingUnavailable": { "value": { "type": "https://whooshbang.flowxo.com/problems/preferred_binding_unavailable", "title": "Preferred binding unavailable", "status": 422, "detail": "The subscriber's preferred binding cannot accept this operation.", "code": "preferred_binding_unavailable", "diagnostic_id": "diag_n17_preference_unavailable", "retryable": false } }, "returnDestinationNotFound": { "value": { "type": "https://whooshbang.flowxo.com/problems/return_destination_not_found", "title": "Return destination not found", "status": 422, "detail": "The registered return destination is unavailable in this environment.", "code": "return_destination_not_found", "diagnostic_id": "diag_n17_return_not_found", "retryable": false } } } } } }, "RecipientCapabilityInvalid": { "description": "The recipient capability is absent, malformed, expired, revoked, or otherwise invalid; no session existence is disclosed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid": { "value": { "type": "https://whooshbang.flowxo.com/problems/recipient_capability_invalid", "title": "Recipient capability invalid", "status": 401, "detail": "The recipient capability is invalid or no longer active.", "code": "recipient_capability_invalid", "diagnostic_id": "diag_n17_capability_invalid", "retryable": false } } } } } }, "RecipientOriginForbidden": { "description": "The presenting exact origin is not allowed by the session's pinned environment configuration.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "value": { "type": "https://whooshbang.flowxo.com/problems/recipient_origin_forbidden", "title": "Recipient origin forbidden", "status": 403, "detail": "The presenting browser origin is not authorized for this recipient session.", "code": "recipient_origin_forbidden", "diagnostic_id": "diag_n17_origin_forbidden", "retryable": false } } } } } }, "ProviderTerminal": { "description": "The endpoint challenge failed in a way that requires developer action.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "providerTerminal": { "value": { "type": "https://whooshbang.flowxo.com/problems/provider_terminal", "title": "Provider terminal failure", "status": 502, "detail": "The provider rejected the operation and no automatic retry is scheduled.", "code": "provider_terminal", "diagnostic_id": "diag_provider_terminal_001", "retryable": false } } } } } }, "ProviderOutcomeUnknown": { "description": "The provider could not be reached, so whether it applied the operation\nis genuinely unknown. Nothing is retried automatically; read the\nresource before deciding what to do.\n", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "providerOutcomeUnknown": { "value": { "type": "https://whooshbang.flowxo.com/problems/provider_outcome_unknown", "title": "Provider outcome unknown", "status": 502, "detail": "The provider may have accepted the operation; no automatic retry is scheduled.", "code": "provider_outcome_unknown", "diagnostic_id": "diag_provider_unknown_002", "retryable": false } } } } } }, "ProviderRetryable": { "description": "The endpoint challenge failed transiently and can be retried safely.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "providerRetryable": { "value": { "type": "https://whooshbang.flowxo.com/problems/provider_retryable", "title": "Provider retryable failure", "status": 503, "detail": "The provider call failed before acceptance and may be retried by the service.", "code": "provider_retryable", "diagnostic_id": "diag_provider_retry_001", "retryable": true, "retry_at": "2026-07-25T17:46:00Z" } } } } } }, "EndpointRotationConflict": { "description": "A previous signing-secret overlap must finish before another rotation.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "endpointRotationConflict": { "value": { "type": "https://whooshbang.flowxo.com/problems/endpoint_rotation_conflict", "title": "Endpoint rotation conflict", "status": 409, "detail": "A prior signing-secret overlap is still active. Retry after that overlap expires.", "code": "endpoint_rotation_conflict", "diagnostic_id": "diag_endpoint_rotation_conflict_001", "retryable": true, "retry_at": "2026-08-06T14:00:00.000Z" } } } } } }, "RateLimited": { "description": "A project or operation rate limit was exceeded.", "headers": { "WhooshBang-Diagnostic-Id": { "$ref": "#/components/headers/DiagnosticId" }, "Retry-After": { "description": "Safe delay in seconds when known.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rateLimited": { "value": { "type": "https://whooshbang.flowxo.com/problems/rate_limited", "title": "Rate limited", "status": 429, "detail": "The project or operation rate limit was exceeded.", "code": "rate_limited", "diagnostic_id": "diag_rate_limited_001", "retryable": true, "retry_at": "2026-07-25T17:46:00Z" } } } } } } } }, "x-contract-version": "1.0.0-rc.25" }