openapi.yaml

openapi: 3.1.0
info:
  title: Webhookery API
  version: 0.1.0
  description: Self-hosted webhook evidence and delivery control plane.
servers:
  - url: http://localhost:8080
tags:
  - name: System
    description: Health, readiness, metrics, and the OpenAPI document.
  - name: API Keys
    description: Management API key lifecycle.
  - name: Producer Trust
    description: Product-event producer credentials, OAuth, and mTLS identities.
  - name: Auth And Identity
    description: OIDC sessions, SCIM, role bindings, access policies, and authorization explanation.
  - name: Sources And Providers
    description: Webhook sources, provider connections, adapters, and provider ingress.
  - name: Endpoints And Routing
    description: Outbound endpoints, subscriptions, routes, and retry policies.
  - name: Schemas And Transformations
    description: Event schemas, compatibility checks, and deterministic transformations.
  - name: Events And Ingestion
    description: Product events, provider ingestion, event evidence, raw payloads, and timelines.
  - name: Incidents
    description: Webhook incident packets, report snapshots, and incident evidence exports.
  - name: Delivery And Replay
    description: Deliveries, attempts, replay jobs, dead letter, and quarantine.
  - name: Reconciliation
    description: Provider reconciliation jobs and gap evidence.
  - name: Audit And Retention
    description: Audit events, audit chain, evidence exports, and retention policies.
  - name: Operations
    description: Operational metrics, storage/config views, workers, queues, and alerts.
  - name: Signal Egress
    description: Notification channels, notification deliveries, SIEM sinks, and SIEM deliveries.
paths:
  /healthz:
    get:
      tags:
        - System
      operationId: getHealthz
      summary: Liveness check
      responses:
        "200":
          description: Process is alive.
  /readyz:
    get:
      tags:
        - System
      operationId: getReadyz
      summary: Readiness check
      responses:
        "200":
          description: Dependencies are ready.
        "503":
          description: A dependency is unavailable.
  /openapi.yaml:
    get:
      tags:
        - System
      operationId: getOpenapiYaml
      summary: OpenAPI document
      responses:
        "200":
          description: YAML OpenAPI document.
  /metrics:
    get:
      tags:
        - System
      operationId: getMetrics
      summary: Prometheus metrics
      responses:
        "200":
          description: Process and queue metrics in Prometheus text format without tenant labels.
          content:
            text/plain:
              schema:
                type: string
  /v1/api-keys:
    get:
      tags:
        - API Keys
      operationId: getApiKeys
      summary: List API keys
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Paginated API key metadata. Key hashes and token values are never returned.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIKeyPage"
    post:
      tags:
        - API Keys
      operationId: postApiKeys
      summary: Create API key
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAPIKeyRequest"
      responses:
        "201":
          description: API key created. The token is returned once.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIKeyCreated"
        "403":
          $ref: "#/components/responses/Problem"
  /v1/api-keys/{api_key_id}:revoke:
    post:
      tags:
        - API Keys
      operationId: postApiKeysApiKeyIdRevoke
      summary: Revoke API key
      security:
        - bearerAuth: []
      parameters:
        - name: api_key_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: API key revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIKey"
  /v1/oauth/token:
    post:
      tags:
        - Producer Trust
      operationId: postOauthToken
      summary: Issue producer OAuth access token
      description: Issues an opaque short-lived bearer token for product-event producers using the client credentials grant. Only HTTP Basic client authentication is accepted; client secrets in the form body are rejected.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/OAuthClientCredentialsRequest"
            example:
              grant_type: client_credentials
              scope: events:write
      responses:
        "200":
          description: Non-cacheable producer access token response.
          headers:
            Cache-Control:
              schema:
                type: string
              description: Always `no-store`.
            Pragma:
              schema:
                type: string
              description: Always `no-cache`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProducerTokenResponse"
              example:
                access_token: "<opaque-access-token>"
                token_type: Bearer
                expires_in: 900
                scope: events:write
        "400":
          $ref: "#/components/responses/Problem"
        "401":
          $ref: "#/components/responses/Problem"
  /v1/producer-clients:
    get:
      tags:
        - Producer Trust
      operationId: getProducerClients
      summary: List producer OAuth clients
      description: Lists tenant-scoped producer client metadata. Client secret hashes and token values are never returned.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Paginated producer client metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProducerClientPage"
    post:
      tags:
        - Producer Trust
      operationId: postProducerClients
      summary: Create producer OAuth client
      description: Creates a tenant/source-bound product-event producer credential. The generated client secret is returned once only.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateProducerClientRequest"
      responses:
        "201":
          description: Producer client created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProducerClientCreated"
        "403":
          $ref: "#/components/responses/Problem"
  /v1/producer-clients/{client_id}:
    get:
      tags:
        - Producer Trust
      operationId: getProducerClientsClientId
      summary: Get producer OAuth client
      security:
        - bearerAuth: []
      parameters:
        - name: client_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Producer client metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProducerClient"
    patch:
      tags:
        - Producer Trust
      operationId: patchProducerClientsClientId
      summary: Update producer OAuth client
      security:
        - bearerAuth: []
      parameters:
        - name: client_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateProducerClientRequest"
      responses:
        "200":
          description: Producer client updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProducerClient"
    delete:
      tags:
        - Producer Trust
      operationId: deleteProducerClientsClientId
      summary: Disable producer OAuth client
      security:
        - bearerAuth: []
      parameters:
        - name: client_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Producer client disabled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProducerClient"
  /v1/producer-clients/{client_id}/secrets:rotate:
    post:
      tags:
        - Producer Trust
      operationId: postProducerClientsClientIdSecretsRotate
      summary: Rotate producer client secret
      description: Revokes active producer client secrets and returns the new client secret once only.
      security:
        - bearerAuth: []
      parameters:
        - name: client_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Producer client secret rotated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProducerClientSecretRotated"
  /v1/producer-mtls-identities:
    get:
      tags:
        - Producer Trust
      operationId: getProducerMtlsIdentities
      summary: List producer mTLS identities
      description: Lists tenant-scoped producer client-certificate identities. Private keys and raw certificate private material are never stored or returned.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Paginated producer mTLS identities.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProducerMTLSIdentityPage"
    post:
      tags:
        - Producer Trust
      operationId: postProducerMtlsIdentities
      summary: Create producer mTLS identity
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateProducerMTLSIdentityRequest"
      responses:
        "201":
          description: Producer mTLS identity created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProducerMTLSIdentity"
  /v1/producer-mtls-identities/{identity_id}:
    get:
      tags:
        - Producer Trust
      operationId: getProducerMtlsIdentitiesIdentityId
      summary: Get producer mTLS identity
      security:
        - bearerAuth: []
      parameters:
        - name: identity_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Producer mTLS identity metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProducerMTLSIdentity"
    patch:
      tags:
        - Producer Trust
      operationId: patchProducerMtlsIdentitiesIdentityId
      summary: Update producer mTLS identity
      security:
        - bearerAuth: []
      parameters:
        - name: identity_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateProducerMTLSIdentityRequest"
      responses:
        "200":
          description: Producer mTLS identity updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProducerMTLSIdentity"
    delete:
      tags:
        - Producer Trust
      operationId: deleteProducerMtlsIdentitiesIdentityId
      summary: Disable producer mTLS identity
      security:
        - bearerAuth: []
      parameters:
        - name: identity_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Producer mTLS identity disabled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProducerMTLSIdentity"
  /v1/producer-mtls-identities/{identity_id}:verify:
    post:
      tags:
        - Producer Trust
      operationId: postProducerMtlsIdentitiesIdentityIdVerify
      summary: Verify producer mTLS certificate against identity
      security:
        - bearerAuth: []
      parameters:
        - name: identity_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VerifyProducerMTLSIdentityRequest"
      responses:
        "200":
          description: Certificate verification result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProducerMTLSIdentityVerification"
  /v1/auth/oidc/login:
    get:
      tags:
        - Auth And Identity
      operationId: getAuthOidcLogin
      summary: Start OIDC management login
      description: Starts Authorization Code + PKCE login for a tenant identity provider and redirects to the provider authorization endpoint.
      parameters:
        - name: tenant_id
          in: query
          required: true
          schema:
            type: string
        - name: provider_id
          in: query
          required: true
          schema:
            type: string
        - name: redirect_after
          in: query
          required: false
          schema:
            type: string
      responses:
        "302":
          description: Redirect to identity provider.
  /v1/auth/oidc/callback:
    get:
      tags:
        - Auth And Identity
      operationId: getAuthOidcCallback
      summary: Complete OIDC management login
      description: Validates state, nonce, issuer, audience, expiry, and signed ID token before creating a hashed management session cookie.
      parameters:
        - name: state
          in: query
          required: true
          schema:
            type: string
        - name: code
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Session created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthSessionCreated"
  /v1/auth/logout:
    post:
      tags:
        - Auth And Identity
      operationId: postAuthLogout
      summary: Revoke current management session
      security:
        - bearerAuth: []
      responses:
        "204":
          description: Session revoked.
  /v1/auth/session:
    get:
      tags:
        - Auth And Identity
      operationId: getAuthSession
      summary: Get current management session
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Current session metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthSession"
              example:
                id: ses_example
                tenant_id: ten_example
                user_id: usr_example
                external_identity_id: oidc_example
                state: active
                created_at: "2026-05-26T12:00:00Z"
                last_seen_at: "2026-05-26T12:05:00Z"
                expires_at: "2026-05-26T20:00:00Z"
  /v1/auth/sessions:
    get:
      tags:
        - Auth And Identity
      operationId: getAuthSessions
      summary: List active management sessions
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Paginated tenant-scoped session metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthSessionPage"
  /v1/auth/sessions/{session_id}:revoke:
    post:
      tags:
        - Auth And Identity
      operationId: postAuthSessionsSessionIdRevoke
      summary: Revoke management session
      security:
        - bearerAuth: []
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Session revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthSession"
  /v1/identity-providers:
    get:
      tags:
        - Auth And Identity
      operationId: getIdentityProviders
      summary: List identity providers
      description: Lists tenant-scoped OIDC identity provider metadata. Client secrets are never returned.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Paginated identity providers.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdentityProviderPage"
    post:
      tags:
        - Auth And Identity
      operationId: postIdentityProviders
      summary: Create OIDC identity provider
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateIdentityProviderRequest"
      responses:
        "201":
          description: Identity provider created with encrypted client secret.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdentityProvider"
  /v1/identity-providers/{provider_id}:
    get:
      tags:
        - Auth And Identity
      operationId: getIdentityProvidersProviderId
      summary: Get identity provider
      security:
        - bearerAuth: []
      parameters:
        - name: provider_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Identity provider metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdentityProvider"
    patch:
      tags:
        - Auth And Identity
      operationId: patchIdentityProvidersProviderId
      summary: Update identity provider
      security:
        - bearerAuth: []
      parameters:
        - name: provider_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateIdentityProviderRequest"
      responses:
        "200":
          description: Identity provider updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdentityProvider"
    delete:
      tags:
        - Auth And Identity
      operationId: deleteIdentityProvidersProviderId
      summary: Disable identity provider
      security:
        - bearerAuth: []
      parameters:
        - name: provider_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Identity provider disabled and active sessions invalidated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdentityProvider"
  /v1/identity-providers/{provider_id}:test:
    post:
      tags:
        - Auth And Identity
      operationId: postIdentityProvidersProviderIdTest
      summary: Test identity provider configuration
      security:
        - bearerAuth: []
      parameters:
        - name: provider_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Identity provider test was recorded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdentityProvider"
  /v1/scim-tokens:
    get:
      tags:
        - Auth And Identity
      operationId: getScimTokens
      summary: List SCIM tokens
      description: Lists SCIM token metadata only. Raw tokens and hashes are never returned.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Paginated SCIM token metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SCIMTokenPage"
    post:
      tags:
        - Auth And Identity
      operationId: postScimTokens
      summary: Create SCIM token
      description: Returns the SCIM bearer token exactly once.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSCIMTokenRequest"
      responses:
        "201":
          description: SCIM token created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SCIMTokenCreated"
  /v1/scim-tokens/{token_id}:
    delete:
      tags:
        - Auth And Identity
      operationId: deleteScimTokensTokenId
      summary: Revoke SCIM token
      security:
        - bearerAuth: []
      parameters:
        - name: token_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: SCIM token revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SCIMToken"
  /v1/scim/v2/Users:
    get:
      tags:
        - Auth And Identity
      operationId: getScimV2Users
      summary: List SCIM users
      security:
        - bearerAuth: []
      responses:
        "200":
          description: SCIM ListResponse.
    post:
      tags:
        - Auth And Identity
      operationId: postScimV2Users
      summary: Provision SCIM user
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SCIMUserRequest"
      responses:
        "201":
          description: User provisioned.
  /v1/scim/v2/Users/{user_id}:
    get:
      tags:
        - Auth And Identity
      operationId: getScimV2UsersUserId
      summary: Get SCIM user
      security:
        - bearerAuth: []
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: SCIM user.
    put:
      tags:
        - Auth And Identity
      operationId: putScimV2UsersUserId
      summary: Replace SCIM user
      security:
        - bearerAuth: []
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SCIMUserRequest"
      responses:
        "200":
          description: User replaced.
    patch:
      tags:
        - Auth And Identity
      operationId: patchScimV2UsersUserId
      summary: Patch SCIM user
      security:
        - bearerAuth: []
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SCIMPatchRequest"
      responses:
        "200":
          description: User patched.
    delete:
      tags:
        - Auth And Identity
      operationId: deleteScimV2UsersUserId
      summary: Deactivate SCIM user
      security:
        - bearerAuth: []
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: User deactivated.
  /v1/scim/v2/Groups:
    get:
      tags:
        - Auth And Identity
      operationId: getScimV2Groups
      summary: List SCIM groups
      security:
        - bearerAuth: []
      responses:
        "200":
          description: SCIM ListResponse.
    post:
      tags:
        - Auth And Identity
      operationId: postScimV2Groups
      summary: Provision SCIM group
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SCIMGroupRequest"
      responses:
        "201":
          description: Group provisioned.
  /v1/scim/v2/Groups/{group_id}:
    get:
      tags:
        - Auth And Identity
      operationId: getScimV2GroupsGroupId
      summary: Get SCIM group
      security:
        - bearerAuth: []
      parameters:
        - name: group_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: SCIM group.
    put:
      tags:
        - Auth And Identity
      operationId: putScimV2GroupsGroupId
      summary: Replace SCIM group
      security:
        - bearerAuth: []
      parameters:
        - name: group_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SCIMGroupRequest"
      responses:
        "200":
          description: Group replaced.
    patch:
      tags:
        - Auth And Identity
      operationId: patchScimV2GroupsGroupId
      summary: Patch SCIM group
      security:
        - bearerAuth: []
      parameters:
        - name: group_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SCIMPatchRequest"
      responses:
        "200":
          description: Group patched.
    delete:
      tags:
        - Auth And Identity
      operationId: deleteScimV2GroupsGroupId
      summary: Deactivate SCIM group
      security:
        - bearerAuth: []
      parameters:
        - name: group_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Group deactivated.
  /v1/role-bindings:
    get:
      tags:
        - Auth And Identity
      operationId: getRoleBindings
      summary: List resource-aware role bindings
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Paginated role bindings.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RoleBindingPage"
    post:
      tags:
        - Auth And Identity
      operationId: postRoleBindings
      summary: Create resource-aware role binding
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRoleBindingRequest"
      responses:
        "201":
          description: Role binding created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RoleBinding"
  /v1/role-bindings/{binding_id}:
    patch:
      tags:
        - Auth And Identity
      operationId: patchRoleBindingsBindingId
      summary: Update role binding
      security:
        - bearerAuth: []
      parameters:
        - name: binding_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateRoleBindingRequest"
      responses:
        "200":
          description: Role binding updated.
    delete:
      tags:
        - Auth And Identity
      operationId: deleteRoleBindingsBindingId
      summary: Disable role binding
      security:
        - bearerAuth: []
      parameters:
        - name: binding_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Role binding disabled.
  /v1/access-policies:
    get:
      tags:
        - Auth And Identity
      operationId: getAccessPolicies
      summary: List access policy rules
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Paginated access policy rules.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccessPolicyRulePage"
    post:
      tags:
        - Auth And Identity
      operationId: postAccessPolicies
      summary: Create access policy rule
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAccessPolicyRuleRequest"
      responses:
        "201":
          description: Access policy rule created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccessPolicyRule"
  /v1/access-policies/{policy_id}:
    patch:
      tags:
        - Auth And Identity
      operationId: patchAccessPoliciesPolicyId
      summary: Update access policy rule
      security:
        - bearerAuth: []
      parameters:
        - name: policy_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateAccessPolicyRuleRequest"
      responses:
        "200":
          description: Access policy rule updated.
    delete:
      tags:
        - Auth And Identity
      operationId: deleteAccessPoliciesPolicyId
      summary: Disable access policy rule
      security:
        - bearerAuth: []
      parameters:
        - name: policy_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Access policy rule disabled.
  /v1/authz:explain:
    post:
      tags:
        - Auth And Identity
      operationId: postAuthzExplain
      summary: Explain authorization decision
      description: Returns a redacted allow/deny explanation for security operators.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuthzExplainRequest"
      responses:
        "200":
          description: Authorization explanation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthzDecision"
  /v1/sources:
    get:
      tags:
        - Sources And Providers
      operationId: getSources
      summary: List inbound sources
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Paginated source list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourcePage"
    post:
      tags:
        - Sources And Providers
      operationId: postSources
      summary: Create inbound source
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSourceRequest"
            example:
              name: stripe-prod
              provider: stripe
              verification_secret: "<webhook-signing-secret>"
      responses:
        "201":
          description: Source created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Source"
  /v1/sources/{source_id}:
    get:
      tags:
        - Sources And Providers
      operationId: getSourcesSourceId
      summary: Get inbound source
      security:
        - bearerAuth: []
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Source metadata without plaintext secrets.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Source"
        "404":
          description: Source not found in this tenant.
    patch:
      tags:
        - Sources And Providers
      operationId: patchSourcesSourceId
      summary: Update inbound source metadata or state
      description: Updates mutable source metadata. Verification secrets are rotated through the dedicated rotate endpoint and are never returned.
      security:
        - bearerAuth: []
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateSourceRequest"
      responses:
        "200":
          description: Updated source metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Source"
    delete:
      tags:
        - Sources And Providers
      operationId: deleteSourcesSourceId
      summary: Disable inbound source
      description: Disables the source without deleting historical evidence.
      security:
        - bearerAuth: []
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Disabled source metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Source"
  /v1/sources/{source_id}/secrets:rotate:
    post:
      tags:
        - Sources And Providers
      operationId: postSourcesSourceIdSecretsRotate
      summary: Rotate source verification secret
      description: Creates a new active source secret version and keeps the previous version during the requested grace period. Plaintext secrets are never returned.
      security:
        - bearerAuth: []
      parameters:
        - name: source_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RotateSourceSecretRequest"
      responses:
        "200":
          description: Source secret version metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourceSecretVersion"
  /v1/provider-connections:
    get:
      tags:
        - Sources And Providers
      operationId: getProviderConnections
      summary: List provider API reconciliation connections
      description: Plaintext provider credentials are never returned.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Paginated provider connection metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderConnectionPage"
    post:
      tags:
        - Sources And Providers
      operationId: postProviderConnections
      summary: Create provider API reconciliation connection
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateProviderConnectionRequest"
            example:
              name: stripe-reconciliation
              provider: stripe
              credential_type: api_key
              credential: "<provider-api-token>"
              config:
                source_id: src_stripe
      responses:
        "201":
          description: Provider connection created with encrypted credentials.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderConnection"
  /v1/provider-connections/{connection_id}:
    get:
      tags:
        - Sources And Providers
      operationId: getProviderConnectionsConnectionId
      summary: Get provider API reconciliation connection
      security:
        - bearerAuth: []
      parameters:
        - name: connection_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Provider connection metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderConnection"
  /v1/provider-connections/{connection_id}:verify:
    post:
      tags:
        - Sources And Providers
      operationId: postProviderConnectionsConnectionIdVerify
      summary: Verify provider API connection credentials
      security:
        - bearerAuth: []
      parameters:
        - name: connection_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Provider connection verified.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderConnection"
  /v1/provider-connections/{connection_id}:revoke:
    post:
      tags:
        - Sources And Providers
      operationId: postProviderConnectionsConnectionIdRevoke
      summary: Revoke provider API connection credentials
      security:
        - bearerAuth: []
      parameters:
        - name: connection_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Provider connection revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderConnection"
  /v1/adapters:
    get:
      tags:
        - Sources And Providers
      operationId: getAdapters
      summary: List built-in and tenant custom adapters
      description: Returns adapter governance metadata only. Plugin packages are not executed by this endpoint.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Paginated adapter metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderAdapterPage"
    post:
      tags:
        - Sources And Providers
      operationId: postAdapters
      summary: Create tenant custom adapter
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateProviderAdapterRequest"
      responses:
        "201":
          description: Adapter created in draft state.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderAdapter"
  /v1/adapters/{adapter_id}:
    get:
      tags:
        - Sources And Providers
      operationId: getAdaptersAdapterId
      summary: Get adapter metadata
      security:
        - bearerAuth: []
      parameters:
        - name: adapter_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Adapter metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderAdapter"
  /v1/adapters/{adapter_id}/versions:
    get:
      tags:
        - Sources And Providers
      operationId: getAdaptersAdapterIdVersions
      summary: List adapter versions
      security:
        - bearerAuth: []
      parameters:
        - name: adapter_id
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Paginated adapter versions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdapterVersionPage"
    post:
      tags:
        - Sources And Providers
      operationId: postAdaptersAdapterIdVersions
      summary: Create adapter version
      description: Declarative versions store JSON definitions. Plugin versions store signed package metadata only and are not executed.
      security:
        - bearerAuth: []
      parameters:
        - name: adapter_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAdapterVersionRequest"
      responses:
        "201":
          description: Adapter version created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdapterVersion"
  /v1/adapters/{adapter_id}/versions/{version_id}/test-vectors:
    post:
      tags:
        - Sources And Providers
      operationId: postAdaptersAdapterIdVersionsVersionIdTestVectors
      summary: Add adapter version test vector
      security:
        - bearerAuth: []
      parameters:
        - name: adapter_id
          in: path
          required: true
          schema:
            type: string
        - name: version_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAdapterTestVectorRequest"
      responses:
        "201":
          description: Test vector metadata and hashes.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdapterTestVector"
  /v1/adapters/{adapter_id}/versions/{version_id}:transition:
    post:
      tags:
        - Sources And Providers
      operationId: postAdaptersAdapterIdVersionsVersionIdTransition
      summary: Transition adapter version through approval workflow
      description: Supported actions are submit_tests, request_review, approve_staging, activate, deprecate, and retire.
      security:
        - bearerAuth: []
      parameters:
        - name: adapter_id
          in: path
          required: true
          schema:
            type: string
        - name: version_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AdapterVersionTransitionRequest"
      responses:
        "200":
          description: Updated adapter version.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdapterVersion"
  /v1/endpoints:
    get:
      tags:
        - Endpoints And Routing
      operationId: getEndpoints
      summary: List outbound endpoints
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Paginated endpoint list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EndpointPage"
    post:
      tags:
        - Endpoints And Routing
      operationId: postEndpoints
      summary: Create outbound endpoint
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateEndpointRequest"
            example:
              name: billing-receiver
              url: https://receiver.example/webhook
      responses:
        "201":
          description: Endpoint created after SSRF validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Endpoint"
  /v1/endpoints/{endpoint_id}:
    get:
      tags:
        - Endpoints And Routing
      operationId: getEndpointsEndpointId
      summary: Get outbound endpoint
      security:
        - bearerAuth: []
      parameters:
        - name: endpoint_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Endpoint metadata without secret or mTLS key material.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Endpoint"
        "404":
          description: Endpoint not found in this tenant.
    patch:
      tags:
        - Endpoints And Routing
      operationId: patchEndpointsEndpointId
      summary: Update outbound endpoint metadata, URL, retry policy, or state
      description: URL updates rerun the SSRF policy before persistence. Signing secrets and mTLS key material are managed through dedicated endpoints.
      security:
        - bearerAuth: []
      parameters:
        - name: endpoint_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateEndpointRequest"
      responses:
        "200":
          description: Updated endpoint metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Endpoint"
        "422":
          description: Endpoint URL blocked by SSRF policy.
    delete:
      tags:
        - Endpoints And Routing
      operationId: deleteEndpointsEndpointId
      summary: Disable outbound endpoint
      description: Disables future delivery claims without deleting historical deliveries, attempts, or evidence.
      security:
        - bearerAuth: []
      parameters:
        - name: endpoint_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Disabled endpoint metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Endpoint"
  /v1/endpoints:validate-url:
    post:
      tags:
        - Endpoints And Routing
      operationId: postEndpointsValidateUrl
      summary: Validate endpoint URL against SSRF policy
      security:
        - bearerAuth: []
      responses:
        "200":
          description: URL validation result.
  /v1/endpoints/{endpoint_id}:test:
    post:
      tags:
        - Endpoints And Routing
      operationId: postEndpointsEndpointIdTest
      summary: Schedule a signed endpoint test delivery
      security:
        - bearerAuth: []
      parameters:
        - name: endpoint_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "202":
          description: Endpoint test delivery scheduled.
  /v1/endpoints/{endpoint_id}/secrets:rotate:
    post:
      tags:
        - Endpoints And Routing
      operationId: postEndpointsEndpointIdSecretsRotate
      summary: Rotate endpoint signing secret
      description: Creates a new active endpoint signing secret version. Outbound deliveries include signing key metadata headers.
      security:
        - bearerAuth: []
      parameters:
        - name: endpoint_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RotateEndpointSecretRequest"
      responses:
        "200":
          description: Endpoint signing secret metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EndpointSecretVersion"
  /v1/subscriptions:
    get:
      tags:
        - Endpoints And Routing
      operationId: getSubscriptions
      summary: List subscriptions
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Paginated subscription list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriptionPage"
    post:
      tags:
        - Endpoints And Routing
      operationId: postSubscriptions
      summary: Create subscription
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSubscriptionRequest"
      responses:
        "201":
          description: Subscription created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Subscription"
  /v1/subscriptions/{subscription_id}:
    get:
      tags:
        - Endpoints And Routing
      operationId: getSubscriptionsSubscriptionId
      summary: Get subscription
      security:
        - bearerAuth: []
      parameters:
        - name: subscription_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Subscription metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Subscription"
        "404":
          description: Subscription not found in this tenant.
    patch:
      tags:
        - Endpoints And Routing
      operationId: patchSubscriptionsSubscriptionId
      summary: Update subscription
      description: Updates fanout configuration and records a new immutable subscription version.
      security:
        - bearerAuth: []
      parameters:
        - name: subscription_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateSubscriptionRequest"
      responses:
        "200":
          description: Updated subscription metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Subscription"
    delete:
      tags:
        - Endpoints And Routing
      operationId: deleteSubscriptionsSubscriptionId
      summary: Disable subscription
      description: Disables future fanout without deleting historical deliveries or configuration evidence.
      security:
        - bearerAuth: []
      parameters:
        - name: subscription_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Disabled subscription metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Subscription"
  /v1/transformations:
    get:
      tags:
        - Schemas And Transformations
      operationId: getTransformations
      summary: List deterministic transformations
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Paginated transformation list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransformationPage"
    post:
      tags:
        - Schemas And Transformations
      operationId: postTransformations
      summary: Create deterministic transformation
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTransformationRequest"
      responses:
        "201":
          description: Transformation created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Transformation"
  /v1/transformations/{transformation_id}:
    get:
      tags:
        - Schemas And Transformations
      operationId: getTransformationsTransformationId
      summary: Get deterministic transformation
      security:
        - bearerAuth: []
      parameters:
        - name: transformation_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Transformation metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Transformation"
  /v1/transformations/{transformation_id}/versions:
    get:
      tags:
        - Schemas And Transformations
      operationId: getTransformationsTransformationIdVersions
      summary: List immutable transformation versions
      security:
        - bearerAuth: []
      parameters:
        - name: transformation_id
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Transformation version snapshots.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransformationVersionPage"
    post:
      tags:
        - Schemas And Transformations
      operationId: postTransformationsTransformationIdVersions
      summary: Create immutable transformation version
      security:
        - bearerAuth: []
      parameters:
        - name: transformation_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTransformationVersionRequest"
      responses:
        "201":
          description: Transformation version created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransformationVersion"
  /v1/transformations/{transformation_id}/versions/{version_id}:activate:
    post:
      tags:
        - Schemas And Transformations
      operationId: postTransformationsTransformationIdVersionsVersionIdActivate
      summary: Activate transformation version
      security:
        - bearerAuth: []
      parameters:
        - name: transformation_id
          in: path
          required: true
          schema:
            type: string
        - name: version_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Transformation version activated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransformationVersion"
  /v1/retry-policies:
    get:
      tags:
        - Endpoints And Routing
      operationId: getRetryPolicies
      summary: List retry policies
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Paginated retry policy list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetryPolicyPage"
    post:
      tags:
        - Endpoints And Routing
      operationId: postRetryPolicies
      summary: Create retry policy version
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRetryPolicyRequest"
      responses:
        "201":
          description: Retry policy version created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetryPolicy"
  /v1/retry-policies/{retry_policy_id}:
    get:
      tags:
        - Endpoints And Routing
      operationId: getRetryPoliciesRetryPolicyId
      summary: Get retry policy
      security:
        - bearerAuth: []
      parameters:
        - name: retry_policy_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Retry policy metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetryPolicy"
        "404":
          description: Retry policy not found in this tenant.
    patch:
      tags:
        - Endpoints And Routing
      operationId: patchRetryPoliciesRetryPolicyId
      summary: Create a new retry policy version from an existing policy
      description: Leaves the existing policy row intact and returns the new version row.
      security:
        - bearerAuth: []
      parameters:
        - name: retry_policy_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateRetryPolicyRequest"
      responses:
        "200":
          description: New retry policy version.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetryPolicy"
    delete:
      tags:
        - Endpoints And Routing
      operationId: deleteRetryPoliciesRetryPolicyId
      summary: Disable retry policy
      description: Disables future use of the referenced retry policy row without deleting historical delivery evidence.
      security:
        - bearerAuth: []
      parameters:
        - name: retry_policy_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Disabled retry policy metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetryPolicy"
  /v1/routes:
    get:
      tags:
        - Endpoints And Routing
      operationId: getRoutes
      summary: List routes
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Paginated route list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RoutePage"
    post:
      tags:
        - Endpoints And Routing
      operationId: postRoutes
      summary: Create route
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRouteRequest"
            example:
              source_id: src_stripe
              name: invoice-events
              endpoint_id: end_billing
              event_types:
                - invoice.paid
                - invoice.updated
              priority: 100
              state: active
      responses:
        "201":
          description: Route created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Route"
  /v1/routes/{route_id}:
    get:
      tags:
        - Endpoints And Routing
      operationId: getRoutesRouteId
      summary: Get route
      security:
        - bearerAuth: []
      parameters:
        - name: route_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Route metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Route"
        "404":
          description: Route not found in this tenant.
    patch:
      tags:
        - Endpoints And Routing
      operationId: patchRoutesRouteId
      summary: Update route
      description: Updates route matching/destination metadata and records a new immutable route version.
      security:
        - bearerAuth: []
      parameters:
        - name: route_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateRouteRequest"
      responses:
        "200":
          description: Updated route metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Route"
    delete:
      tags:
        - Endpoints And Routing
      operationId: deleteRoutesRouteId
      summary: Inactivate route
      description: Moves the route to inactive without deleting historical decisions, deliveries, or version evidence.
      security:
        - bearerAuth: []
      parameters:
        - name: route_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Inactivated route metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Route"
  /v1/routes/{route_id}/versions:
    get:
      tags:
        - Endpoints And Routing
      operationId: getRoutesRouteIdVersions
      summary: List immutable route versions
      security:
        - bearerAuth: []
      parameters:
        - name: route_id
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Route version snapshots.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RouteVersionPage"
  /v1/routes/{route_id}:activate:
    post:
      tags:
        - Endpoints And Routing
      operationId: postRoutesRouteIdActivate
      summary: Activate route
      security:
        - bearerAuth: []
      parameters:
        - name: route_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Route activated.
  /v1/routes/{route_id}:dry-run:
    post:
      tags:
        - Endpoints And Routing
      operationId: postRoutesRouteIdDryRun
      summary: Dry-run route against event
      security:
        - bearerAuth: []
      parameters:
        - name: route_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Route match explanation.
  /v1/event-types:
    get:
      tags:
        - Schemas And Transformations
      operationId: getEventTypes
      summary: List event types
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Paginated event type list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventTypePage"
    post:
      tags:
        - Schemas And Transformations
      operationId: postEventTypes
      summary: Create event type
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateEventTypeRequest"
      responses:
        "201":
          description: Event type created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventType"
  /v1/event-types/{event_type}:
    get:
      tags:
        - Schemas And Transformations
      operationId: getEventTypesEventType
      summary: Get event type
      security:
        - bearerAuth: []
      parameters:
        - name: event_type
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Event type metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventType"
        "404":
          description: Event type not found in this tenant.
    patch:
      tags:
        - Schemas And Transformations
      operationId: patchEventTypesEventType
      summary: Update event type metadata or state
      description: Event type names remain immutable; delete disables the event type.
      security:
        - bearerAuth: []
      parameters:
        - name: event_type
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateEventTypeRequest"
      responses:
        "200":
          description: Event type updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventType"
    delete:
      tags:
        - Schemas And Transformations
      operationId: deleteEventTypesEventType
      summary: Disable event type
      description: Event type delete is a state transition to disabled; historical schemas and evidence remain.
      security:
        - bearerAuth: []
      parameters:
        - name: event_type
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StateChangeRequest"
      responses:
        "200":
          description: Event type disabled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventType"
  /v1/event-types/{event_type}/schemas:
    get:
      tags:
        - Schemas And Transformations
      operationId: getEventTypesEventTypeSchemas
      summary: List schemas for event type
      security:
        - bearerAuth: []
      parameters:
        - name: event_type
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Paginated schema list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventSchemaPage"
    post:
      tags:
        - Schemas And Transformations
      operationId: postEventTypesEventTypeSchemas
      summary: Create schema for event type
      security:
        - bearerAuth: []
      parameters:
        - name: event_type
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateEventSchemaRequest"
      responses:
        "201":
          description: Schema created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventSchema"
  /v1/event-types/{event_type}/schemas/{schema_version}:
    get:
      tags:
        - Schemas And Transformations
      operationId: getEventTypesEventTypeSchemasSchemaVersion
      summary: Get schema for event type
      security:
        - bearerAuth: []
      parameters:
        - name: event_type
          in: path
          required: true
          schema:
            type: string
        - name: schema_version
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Event schema metadata and JSON schema text.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventSchema"
        "404":
          description: Schema not found in this tenant.
    patch:
      tags:
        - Schemas And Transformations
      operationId: patchEventTypesEventTypeSchemasSchemaVersion
      summary: Update schema lifecycle state
      description: Schema body and version remain immutable; lifecycle state changes are audited and config-versioned.
      security:
        - bearerAuth: []
      parameters:
        - name: event_type
          in: path
          required: true
          schema:
            type: string
        - name: schema_version
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateEventSchemaRequest"
      responses:
        "200":
          description: Event schema updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventSchema"
    delete:
      tags:
        - Schemas And Transformations
      operationId: deleteEventTypesEventTypeSchemasSchemaVersion
      summary: Retire schema
      description: Schema delete is a state transition to retired; historical evidence remains.
      security:
        - bearerAuth: []
      parameters:
        - name: event_type
          in: path
          required: true
          schema:
            type: string
        - name: schema_version
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StateChangeRequest"
      responses:
        "200":
          description: Event schema retired.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventSchema"
  /v1/event-types/{event_type}/schemas/{schema_version}:validate:
    post:
      tags:
        - Schemas And Transformations
      operationId: postEventTypesEventTypeSchemasSchemaVersionValidate
      summary: Validate payload against schema
      security:
        - bearerAuth: []
      parameters:
        - name: event_type
          in: path
          required: true
          schema:
            type: string
        - name: schema_version
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ValidateSchemaRequest"
      responses:
        "200":
          description: Validation result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SchemaValidationResult"
  /v1/event-types/{event_type}/schemas/{schema_version}:check-compatibility:
    post:
      tags:
        - Schemas And Transformations
      operationId: postEventTypesEventTypeSchemasSchemaVersionCheckCompatibility
      summary: Check schema compatibility
      description: Performs conservative JSON-object compatibility checks for required fields and property type changes.
      security:
        - bearerAuth: []
      parameters:
        - name: event_type
          in: path
          required: true
          schema:
            type: string
        - name: schema_version
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CheckSchemaCompatibilityRequest"
      responses:
        "200":
          description: Compatibility result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SchemaCompatibilityResult"
  /v1/events:
    get:
      tags:
        - Events And Ingestion
      operationId: getEvents
      summary: Search events
      security:
        - bearerAuth: []
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: provider
          in: query
          schema:
            type: string
          description: Provider name, such as `stripe`, `github`, or `shopify`.
        - name: external_id
          in: query
          schema:
            type: string
          description: Provider event ID, such as a Stripe event ID.
        - name: delivery_id
          in: query
          schema:
            type: string
          description: Webhookery delivery ID linked to the event.
        - name: status
          in: query
          schema:
            type: string
            enum: [dlq, dead_lettered]
          description: Forensic status preset. `dlq` and `dead_lettered` return events with open DLQ evidence.
        - name: verification
          in: query
          schema:
            type: string
            enum: [valid, invalid]
          description: Provider signature verification result.
        - name: received_after
          in: query
          schema:
            type: string
            format: date-time
          description: Lower bound for event receipt time.
        - name: route_id
          in: query
          schema:
            type: string
          description: Route ID with delivery evidence linked to the event.
      responses:
        "200":
          description: Paginated event list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventPage"
        "400":
          $ref: "#/components/responses/ValidationProblem"
    post:
      tags:
        - Events And Ingestion
      operationId: postEvents
      summary: Ingest product event
      description: Accepts product events from management API keys, producer OAuth bearer tokens, or verified producer mTLS identities. Source-bound credentials must match the submitted `source_id`.
      security:
        - bearerAuth: []
        - producerMTLS: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProductEventIngestRequest"
            example:
              source_id: src_internal
              id: evt_demo_001
              type: demo.created
              data:
                ok: true
      responses:
        "202":
          description: Product event accepted after durable capture.
          content:
            application/json:
              example:
                Accepted: true
                EventID: evt_example
                ReceiptID: rcp_example
                RawPayloadID: raw_example
                TraceID: req_example
                VerifyReason: verified
                DedupeStatus: unique
        "400":
          $ref: "#/components/responses/ValidationProblem"
        "401":
          $ref: "#/components/responses/UnauthorizedProblem"
        "403":
          $ref: "#/components/responses/ForbiddenProblem"
  /v1/events/{event_id}:
    get:
      tags:
        - Events And Ingestion
      operationId: getEventsEventId
      summary: Get event
      security:
        - bearerAuth: []
      parameters:
        - name: event_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Event detail.
          content:
            application/json:
              example:
                id: evt_example
                source_id: src_internal
                event_type: demo.created
                verification_status: verified
                dedupe_status: unique
                created_at: "2026-05-26T12:00:00Z"
        "404":
          $ref: "#/components/responses/NotFoundProblem"
  /v1/events/{event_id}/raw:
    get:
      tags:
        - Events And Ingestion
      operationId: getEventsEventIdRaw
      summary: Get raw payload evidence
      security:
        - bearerAuth: []
      parameters:
        - name: event_id
          in: path
          required: true
          schema:
            type: string
        - name: reason
          in: query
          required: true
          description: Operator reason for elevated raw payload access. The reason is recorded on the raw_payload.read audit event.
          schema:
            type: string
            minLength: 1
            maxLength: 500
      responses:
        "200":
          description: Raw body as base64 plus hash and storage metadata.
          content:
            application/json:
              example:
                event_id: evt_example
                raw_payload_hash: sha256:0f343b0931126a20f133d67c2b018a3b
                content_type: application/json
                size_bytes: 42
                storage_backend: postgres
                storage_status: stored
                body_base64: eyJpZCI6ImV2dF9leGFtcGxlIn0=
        "400":
          $ref: "#/components/responses/ValidationProblem"
        "403":
          $ref: "#/components/responses/ForbiddenProblem"
        "410":
          description: Raw payload body has expired or was deleted by retention; metadata remains on related records.
  /v1/events/{event_id}/normalized:
    get:
      tags:
        - Events And Ingestion
      operationId: getEventsEventIdNormalized
      summary: Get normalized event evidence
      description: Metadata and hashes require events:read. Including normalized data requires events:raw and writes an audit event.
      security:
        - bearerAuth: []
      parameters:
        - name: event_id
          in: path
          required: true
          schema:
            type: string
        - name: include_data
          in: query
          required: false
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: Normalized envelope metadata, hashes, and optionally body data.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NormalizedEnvelope"
        "403":
          $ref: "#/components/responses/ForbiddenProblem"
        "410":
          description: Normalized data was deleted by retention; metadata and hashes remain.
  /v1/events/{event_id}/timeline:
    get:
      tags:
        - Events And Ingestion
      operationId: getEventsEventIdTimeline
      summary: Get event timeline
      security:
        - bearerAuth: []
      parameters:
        - name: event_id
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Timeline entries for event, receipts, deliveries, attempts, and audit records.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventTimelinePage"
  /v1/incidents:
    get:
      tags:
        - Incidents
      operationId: getIncidents
      summary: List webhook incidents
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Paginated tenant-scoped incidents.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IncidentPage"
    post:
      tags:
        - Incidents
      operationId: postIncidents
      summary: Create webhook incident
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateIncidentRequest"
            example:
              title: "Stripe payment webhook failed"
              reason: "customer support investigation"
      responses:
        "201":
          description: Incident created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Incident"
        "403":
          $ref: "#/components/responses/ForbiddenProblem"
  /v1/incidents/{incident_id}:
    get:
      tags:
        - Incidents
      operationId: getIncidentsIncidentId
      summary: Get webhook incident
      security:
        - bearerAuth: []
      parameters:
        - name: incident_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Incident metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Incident"
        "404":
          description: Incident not found or not visible.
  /v1/incidents/{incident_id}/events:
    post:
      tags:
        - Incidents
      operationId: postIncidentsIncidentIdEvents
      summary: Attach event to incident
      security:
        - bearerAuth: []
      parameters:
        - name: incident_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddIncidentEventRequest"
            example:
              event_id: evt_example
              reason: "failed downstream delivery"
      responses:
        "201":
          description: Event attached to incident.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IncidentEvent"
        "404":
          description: Incident or event not found in the actor tenant.
  /v1/incidents/{incident_id}/events/{event_id}:
    delete:
      tags:
        - Incidents
      operationId: deleteIncidentsIncidentIdEventsEventId
      summary: Remove event from incident
      security:
        - bearerAuth: []
      parameters:
        - name: incident_id
          in: path
          required: true
          schema:
            type: string
        - name: event_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StateChangeRequest"
            example:
              reason: "event not related to this incident"
      responses:
        "200":
          description: Event removed from incident.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IncidentEvent"
  /v1/incidents/{incident_id}/generate-report:
    post:
      tags:
        - Incidents
      operationId: postIncidentsIncidentIdGenerateReport
      summary: Generate incident report snapshot
      description: Generates a tenant-scoped JSON and Markdown report from attached event timelines. Raw payload bodies are omitted by default.
      security:
        - bearerAuth: []
      parameters:
        - name: incident_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IncidentReportRequest"
            example:
              reason: "support handoff"
      responses:
        "201":
          description: Incident report snapshot generated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IncidentReportSnapshot"
  /v1/incidents/{incident_id}/report:
    get:
      tags:
        - Incidents
      operationId: getIncidentsIncidentIdReport
      summary: Get latest incident report snapshot
      security:
        - bearerAuth: []
      parameters:
        - name: incident_id
          in: path
          required: true
          schema:
            type: string
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [json, markdown]
            default: json
      responses:
        "200":
          description: Latest incident report snapshot.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IncidentReportSnapshot"
            text/markdown:
              schema:
                type: string
  /v1/incidents/{incident_id}/evidence-export:
    post:
      tags:
        - Incidents
      operationId: postIncidentsIncidentIdEvidenceExport
      summary: Create incident evidence export
      description: Creates a tenant-scoped evidence bundle that includes incident_report.json and incident_report.md. Raw payload bodies are excluded.
      security:
        - bearerAuth: []
      parameters:
        - name: incident_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateIncidentEvidenceExportRequest"
            example:
              reason: "customer evidence package"
      responses:
        "202":
          description: Incident evidence export created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EvidenceExport"
  /v1/ingest/{tenant_id}/{source_id}:
    post:
      tags:
        - Events And Ingestion
      operationId: postIngestTenantIdSourceId
      summary: Generic provider webhook ingestion
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
        - name: source_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            example:
              id: evt_provider_123
              type: invoice.paid
              data:
                object: invoice
      responses:
        "200":
          description: Accepted after durable capture.
          content:
            application/json:
              example:
                Accepted: true
                EventID: evt_example
                ReceiptID: rcp_example
                RawPayloadID: raw_example
                TraceID: ""
                VerifyReason: verified
                DedupeStatus: unique
        "401":
          $ref: "#/components/responses/UnauthorizedProblem"
        "413":
          $ref: "#/components/responses/PayloadTooLargeProblem"
        "431":
          $ref: "#/components/responses/HeadersTooLargeProblem"
        "503":
          $ref: "#/components/responses/StorageUnavailableProblem"
  /v1/ingest/stripe/{source_id}:
    post:
      tags:
        - Events And Ingestion
      operationId: postIngestStripeSourceId
      summary: Stripe webhook ingestion
      responses:
        "200":
          description: Accepted after durable capture.
        "431":
          $ref: "#/components/responses/HeadersTooLargeProblem"
  /v1/ingest/github/{source_id}:
    post:
      tags:
        - Events And Ingestion
      operationId: postIngestGithubSourceId
      summary: GitHub webhook ingestion
      responses:
        "200":
          description: Accepted after durable capture.
        "431":
          $ref: "#/components/responses/HeadersTooLargeProblem"
  /v1/ingest/shopify/{source_id}:
    post:
      tags:
        - Events And Ingestion
      operationId: postIngestShopifySourceId
      summary: Shopify webhook ingestion
      responses:
        "200":
          description: Accepted after durable capture.
        "431":
          $ref: "#/components/responses/HeadersTooLargeProblem"
  /v1/ingest/slack/{source_id}:
    post:
      tags:
        - Events And Ingestion
      operationId: postIngestSlackSourceId
      summary: Slack webhook ingestion
      responses:
        "200":
          description: Accepted after durable capture.
        "431":
          $ref: "#/components/responses/HeadersTooLargeProblem"
  /v1/ingest/cloudevents/{source_id}:
    post:
      tags:
        - Events And Ingestion
      operationId: postIngestCloudeventsSourceId
      summary: CloudEvents webhook ingestion
      responses:
        "200":
          description: Accepted after durable capture for binary or structured CloudEvents envelopes.
        "431":
          $ref: "#/components/responses/HeadersTooLargeProblem"
  /v1/ingest/generic-jwt/{source_id}:
    post:
      tags:
        - Events And Ingestion
      operationId: postIngestGenericJwtSourceId
      summary: Generic JWT/JWS webhook ingestion
      description: "Accepts compact JWT/JWS signatures from `Authorization: Bearer ...` or `Webhook-JWT`; only HS256 is supported and the token must include `exp` plus a `body_sha256` claim for the exact raw body."
      responses:
        "200":
          description: Accepted after durable capture.
        "401":
          description: Invalid or unsupported JWT signature.
        "431":
          $ref: "#/components/responses/HeadersTooLargeProblem"
  /v1/deliveries:
    get:
      tags:
        - Delivery And Replay
      operationId: getDeliveries
      summary: List deliveries
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Paginated delivery list, including retry seed evidence for reproducible scheduling.
  /v1/deliveries/{delivery_id}/attempts:
    get:
      tags:
        - Delivery And Replay
      operationId: getDeliveriesDeliveryIdAttempts
      summary: List delivery attempts
      security:
        - bearerAuth: []
      parameters:
        - name: delivery_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Paginated delivery attempts, including deterministic retry delay and next retry timestamp when retryable.
  /v1/deliveries/{delivery_id}:retry:
    post:
      tags:
        - Delivery And Replay
      operationId: postDeliveriesDeliveryIdRetry
      summary: Manually retry delivery
      security:
        - bearerAuth: []
      parameters:
        - name: delivery_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "202":
          description: Delivery retry scheduled.
  /v1/deliveries/{delivery_id}:cancel:
    post:
      tags:
        - Delivery And Replay
      operationId: postDeliveriesDeliveryIdCancel
      summary: Cancel scheduled delivery
      security:
        - bearerAuth: []
      parameters:
        - name: delivery_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Delivery canceled.
  /v1/delivery-attempts/{attempt_id}:
    get:
      tags:
        - Delivery And Replay
      operationId: getDeliveryAttemptsAttemptId
      summary: Get delivery attempt
      security:
        - bearerAuth: []
      parameters:
        - name: attempt_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Delivery attempt detail, including deterministic retry delay evidence when retryable.
  /v1/replay-jobs:dry-run:
    post:
      tags:
        - Delivery And Replay
      operationId: postReplayJobsDryRun
      summary: Dry-run replay
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReplayRequest"
      responses:
        "200":
          description: Replay dry-run result.
  /v1/replay-jobs/preview:
    post:
      tags:
        - Delivery And Replay
      operationId: postReplayJobsPreview
      summary: Preview replay
      description: Additive alias for replay dry-run. It validates the same request and does not create replay jobs or delivery work.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReplayRequest"
      responses:
        "200":
          description: Replay preview result.
  /v1/replay-jobs:
    get:
      tags:
        - Delivery And Replay
      operationId: getReplayJobs
      summary: List replay jobs
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Paginated replay job list.
    post:
      tags:
        - Delivery And Replay
      operationId: postReplayJobs
      summary: Create replay job
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReplayRequest"
            example:
              event_id: evt_example
              endpoint_id: end_example
              reason_code: receiver_fixed
              reason: "customer requested replay after downstream fix"
              config_mode: current
              rate_limit_per_minute: 60
              require_approval: true
              approval_expires_at: "2026-06-05T12:00:00Z"
      responses:
        "202":
          description: Replay job scheduled or pending approval when require_approval is true.
          content:
            application/json:
              example:
                id: rpl_example
                state: pending_approval
                scope_hash: sha256:2c26b46b68ffc68ff99b453c1d304134
                reason_code: receiver_fixed
                reason: "customer requested replay after downstream fix"
                config_mode: current
                rate_limit_per_minute: 60
                total_items: 1
                processed_items: 0
                failed_items: 0
                approval_required: true
                approval_expires_at: "2026-06-05T12:00:00Z"
  /v1/replay-jobs/{replay_job_id}:approve:
    post:
      tags:
        - Delivery And Replay
      operationId: postReplayJobsReplayJobIdApprove
      summary: Approve pending replay job
      description: Moves a tenant-scoped pending replay job into scheduled state and enqueues durable replay work. The approving actor must be different from the creator and the approval window must not be expired.
      security:
        - bearerAuth: []
      parameters:
        - name: replay_job_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Replay job approved and scheduled.
  /v1/replay-jobs/{replay_job_id}:pause:
    post:
      tags:
        - Delivery And Replay
      operationId: postReplayJobsReplayJobIdPause
      summary: Pause replay job
      security:
        - bearerAuth: []
      parameters:
        - name: replay_job_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Replay job paused.
  /v1/replay-jobs/{replay_job_id}:resume:
    post:
      tags:
        - Delivery And Replay
      operationId: postReplayJobsReplayJobIdResume
      summary: Resume replay job
      security:
        - bearerAuth: []
      parameters:
        - name: replay_job_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Replay job scheduled again.
  /v1/replay-jobs/{replay_job_id}:cancel:
    post:
      tags:
        - Delivery And Replay
      operationId: postReplayJobsReplayJobIdCancel
      summary: Cancel replay job
      security:
        - bearerAuth: []
      parameters:
        - name: replay_job_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Replay job canceled.
  /v1/replay-approval-policies:
    get:
      tags:
        - Delivery And Replay
      operationId: getReplayApprovalPolicies
      summary: List replay approval policies
      description: Lists tenant-scoped policies that automatically require replay approval for tenant, source, or route scopes.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Paginated replay approval policy list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReplayApprovalPolicyPage"
    post:
      tags:
        - Delivery And Replay
      operationId: postReplayApprovalPolicies
      summary: Create or reactivate replay approval policy
      description: Creates or reactivates an active policy that makes matching replay jobs pending approval before delivery work is enqueued.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateReplayApprovalPolicyRequest"
            example:
              scope_type: source
              scope_id: src_stripe
              default_expiry_seconds: 86400
              reason: "payments source requires maker-checker replay"
      responses:
        "201":
          description: Replay approval policy created or reactivated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReplayApprovalPolicy"
  /v1/replay-approval-policies/{policy_id}:
    delete:
      tags:
        - Delivery And Replay
      operationId: deleteReplayApprovalPoliciesPolicyId
      summary: Disable replay approval policy
      description: Disables a tenant-scoped replay approval policy. Historical pending jobs keep their approval requirement.
      security:
        - bearerAuth: []
      parameters:
        - name: policy_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Replay approval policy disabled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReplayApprovalPolicy"
  /v1/reconciliation-jobs:dry-run:
    post:
      tags:
        - Reconciliation
      operationId: postReconciliationJobsDryRun
      summary: Dry-run provider reconciliation
      description: Reports expected matched, missing, recoverable, redelivery, or unrecoverable outcomes without capturing recovered events or requesting redelivery.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReconciliationJobRequest"
      responses:
        "200":
          description: Dry-run reconciliation result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReconciliationJob"
  /v1/reconciliation-jobs:
    get:
      tags:
        - Reconciliation
      operationId: getReconciliationJobs
      summary: List provider reconciliation jobs
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Paginated reconciliation jobs.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReconciliationJobPage"
    post:
      tags:
        - Reconciliation
      operationId: postReconciliationJobs
      summary: Create provider reconciliation job
      description: Recovered provider API events are not marked as signed webhooks and route only when `route_recovered=true`.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReconciliationJobRequest"
            examples:
              stripe_recovery:
                value:
                  connection_id: pcn_stripe
                  window_start: "2026-05-25T00:00:00Z"
                  window_end: "2026-05-25T12:00:00Z"
                  capture_missing: true
                  route_recovered: true
                  reason: support case recovery
              github_redelivery:
                value:
                  connection_id: pcn_github
                  redeliver_failed: true
                  reason: request GitHub redelivery for failed deliveries
      responses:
        "201":
          description: Reconciliation job scheduled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReconciliationJob"
  /v1/reconciliation-jobs/{job_id}:
    get:
      tags:
        - Reconciliation
      operationId: getReconciliationJobsJobId
      summary: Get provider reconciliation job
      security:
        - bearerAuth: []
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Reconciliation job.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReconciliationJob"
  /v1/reconciliation-jobs/{job_id}/items:
    get:
      tags:
        - Reconciliation
      operationId: getReconciliationJobsJobIdItems
      summary: List provider reconciliation gap items
      security:
        - bearerAuth: []
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Paginated reconciliation items.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReconciliationItemPage"
  /v1/reconciliation-jobs/{job_id}:cancel:
    post:
      tags:
        - Reconciliation
      operationId: postReconciliationJobsJobIdCancel
      summary: Cancel provider reconciliation job
      security:
        - bearerAuth: []
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReasonRequest"
      responses:
        "200":
          description: Reconciliation job canceled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReconciliationJob"
  /v1/dead-letter:
    get:
      tags:
        - Delivery And Replay
      operationId: getDeadLetter
      summary: List dead-letter entries
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Paginated dead-letter list.
  /v1/dead-letter/{entry_id}:release:
    post:
      tags:
        - Delivery And Replay
      operationId: postDeadLetterEntryIdRelease
      summary: Release dead-letter entry into replay work
      security:
        - bearerAuth: []
      parameters:
        - name: entry_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeadLetterReleaseRequest"
      responses:
        "202":
          description: Replay job scheduled for dead-letter entry.
  /v1/dead-letter:bulk-release:
    post:
      tags:
        - Delivery And Replay
      operationId: postDeadLetterBulkRelease
      summary: Bulk release dead-letter entries
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeadLetterBulkReleaseRequest"
      responses:
        "202":
          description: Replay jobs scheduled for matching dead-letter entries.
  /v1/quarantine:
    get:
      tags:
        - Delivery And Replay
      operationId: getQuarantine
      summary: List quarantine entries
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Paginated quarantine list.
  /v1/quarantine/{entry_id}:approve:
    post:
      tags:
        - Delivery And Replay
      operationId: postQuarantineEntryIdApprove
      summary: Approve quarantine entry
      security:
        - bearerAuth: []
      parameters:
        - name: entry_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Quarantine entry approved.
  /v1/quarantine/{entry_id}:reject:
    post:
      tags:
        - Delivery And Replay
      operationId: postQuarantineEntryIdReject
      summary: Reject quarantine entry
      security:
        - bearerAuth: []
      parameters:
        - name: entry_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Quarantine entry rejected.
  /v1/audit-events:
    get:
      tags:
        - Audit And Retention
      operationId: getAuditEvents
      summary: List audit events
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Paginated audit event list.
  /v1/audit-chain/head:
    get:
      tags:
        - Audit And Retention
      operationId: getAuditChainHead
      summary: Get audit chain head
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Current tenant audit chain head and anchor metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditChainHead"
  /v1/audit-chain:verify:
    post:
      tags:
        - Audit And Retention
      operationId: postAuditChainVerify
      summary: Verify audit chain continuity
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuditChainVerifyRequest"
      responses:
        "200":
          description: Verification result for the requested tenant chain range.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditChainVerification"
  /v1/audit-chain:anchor:
    post:
      tags:
        - Audit And Retention
      operationId: postAuditChainAnchor
      summary: Anchor a verified audit chain range
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuditChainAnchorRequest"
      responses:
        "201":
          description: Anchor created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditChainAnchor"
        "403":
          description: Actor lacks security:write.
  /v1/audit-chain/anchors:
    get:
      tags:
        - Audit And Retention
      operationId: getAuditChainAnchors
      summary: List audit chain anchors
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Paginated audit chain anchors.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditChainAnchorPage"
  /v1/audit-chain/anchors/{anchor_id}:
    get:
      tags:
        - Audit And Retention
      operationId: getAuditChainAnchorsAnchorId
      summary: Get audit chain anchor
      security:
        - bearerAuth: []
      parameters:
        - name: anchor_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Audit chain anchor metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditChainAnchor"
        "404":
          description: Anchor not found.
  /v1/audit-events:export:
    post:
      tags:
        - Audit And Retention
      operationId: postAuditEventsExport
      summary: Create audit evidence export
      description: Creates a tenant-scoped tar.gz bundle containing manifest.json, audit_events.jsonl, and optional timeline or raw payload JSONL files. Raw payload bodies require events:raw in addition to audit:read.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAuditExportRequest"
            example:
              from: "2026-05-26T00:00:00Z"
              to: "2026-05-26T23:59:59Z"
              include_raw_payloads: true
              include_payload_bodies: false
              include_timelines: true
              reason: "support evidence package"
      responses:
        "202":
          description: Export created and ready for download.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EvidenceExport"
              example:
                id: exp_example
                tenant_id: ten_example
                state: ready
                include_raw_payloads: true
                include_timelines: true
                include_payload_bodies: false
                format: tar+gzip+jsonl
                storage_backend: postgres
                sha256: sha256:2c26b46b68ffc68ff99b453c1d304134
                manifest_sha256: sha256:fcde2b2edba56bf408601fb721fe9b5c
                size_bytes: 4096
                created_by: usr_example
                created_at: "2026-05-26T12:00:00Z"
        "403":
          description: Actor lacks audit:read or requested raw payload bodies without events:raw.
  /v1/audit-exports:
    get:
      tags:
        - Audit And Retention
      operationId: getAuditExports
      summary: List audit evidence exports
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Paginated tenant-scoped export jobs. Raw-inclusive exports are hidden from actors without events:raw.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EvidenceExportPage"
  /v1/audit-exports/{export_id}:
    get:
      tags:
        - Audit And Retention
      operationId: getAuditExportsExportId
      summary: Get audit evidence export status
      security:
        - bearerAuth: []
      parameters:
        - name: export_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Export job status and hashes.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EvidenceExport"
        "404":
          description: Export not found or not visible.
  /v1/audit-exports/{export_id}:download:
    get:
      tags:
        - Audit And Retention
      operationId: getAuditExportsExportIdDownload
      summary: Download audit evidence export bundle
      security:
        - bearerAuth: []
      parameters:
        - name: export_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Gzipped tar bundle containing manifest.json and JSONL files.
          headers:
            X-Webhookery-Export-SHA256:
              schema:
                type: string
          content:
            application/gzip:
              schema:
                type: string
                format: binary
        "403":
          description: Actor lacks permission for this export.
        "410":
          description: Export bundle is unavailable.
  /v1/admin/retention-policies:
    get:
      tags:
        - Audit And Retention
      operationId: getAdminRetentionPolicies
      summary: List retention policies
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Paginated retention policy list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetentionPolicyPage"
    post:
      tags:
        - Audit And Retention
      operationId: postAdminRetentionPolicies
      summary: Create or update retention policy
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRetentionPolicyRequest"
      responses:
        "201":
          description: Retention policy created or upserted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetentionPolicy"
  /v1/admin/retention-policies/{policy_id}:
    patch:
      tags:
        - Audit And Retention
      operationId: patchAdminRetentionPoliciesPolicyId
      summary: Update retention policy
      security:
        - bearerAuth: []
      parameters:
        - name: policy_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateRetentionPolicyRequest"
      responses:
        "200":
          description: Retention policy updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetentionPolicy"
  /v1/endpoint-health:
    get:
      tags:
        - Operations
      operationId: getEndpointHealth
      summary: List endpoint health
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Paginated endpoint health summaries.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EndpointHealthPage"
  /v1/ops/metrics:
    get:
      tags:
        - Operations
      operationId: getOpsMetrics
      summary: Get tenant ops metrics
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Tenant-scoped operational metrics.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpsMetrics"
  /v1/ops/metrics/rollups:
    get:
      tags:
        - Operations
      operationId: getOpsMetricsRollups
      summary: List tenant metrics rollups
      description: Returns tenant-scoped derived operational rollups. Rollups summarize state for dashboards and alerts and are not evidence source-of-truth.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Limit"
        - name: metric_name
          in: query
          required: false
          schema:
            type: string
            maxLength: 128
      responses:
        "200":
          description: Paginated metrics rollups.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MetricRollupPage"
        "400":
          description: Invalid metric filter.
  /v1/ops/storage:
    get:
      tags:
        - Operations
      operationId: getOpsStorage
      summary: Get tenant storage status
      description: Returns redacted storage metadata and tenant-scoped counts without object-store credentials or raw payload bodies.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Tenant-scoped storage status.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpsStorageStatus"
  /v1/ops/config:
    get:
      tags:
        - Operations
      operationId: getOpsConfig
      summary: Get redacted runtime configuration
      description: Returns safe runtime configuration metadata only; secret values and connection strings are never included.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Redacted runtime configuration metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpsConfig"
  /v1/ops/workers:
    get:
      tags:
        - Operations
      operationId: getOpsWorkers
      summary: List worker leases
      description: Lists runtime worker lease metadata only; no tenant payload data is exposed.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Paginated worker status list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkerStatusPage"
  /v1/ops/workers/{worker_id}:
    get:
      tags:
        - Operations
      operationId: getOpsWorkersWorkerId
      summary: Get worker lease
      security:
        - bearerAuth: []
      parameters:
        - name: worker_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Worker lease metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkerStatus"
        "404":
          description: Worker lease not found.
  /v1/ops/queues:
    get:
      tags:
        - Operations
      operationId: getOpsQueues
      summary: List tenant queue stats
      description: Returns tenant-scoped durable outbox and delivery queue counts.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Paginated queue statistics.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueueStatsPage"
  /v1/alerts:
    get:
      tags:
        - Operations
      operationId: getAlerts
      summary: List alert rules
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Paginated alert rules.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlertRulePage"
    post:
      tags:
        - Operations
      operationId: postAlerts
      summary: Create alert rule
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAlertRuleRequest"
            example:
              name: "DLQ backlog"
              rule_type: dead_letter_open
              metric_name: dead_letter.open
              threshold: 0
              comparator: ">"
              window_seconds: 300
              state: active
      responses:
        "201":
          description: Alert rule created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlertRule"
              example:
                id: alr_example
                tenant_id: ten_example
                name: "DLQ backlog"
                rule_type: dead_letter_open
                metric_name: dead_letter.open
                threshold: 0
                comparator: ">"
                window_seconds: 300
                state: active
                created_by: usr_example
                created_at: "2026-05-26T12:00:00Z"
                updated_at: "2026-05-26T12:00:00Z"
        "403":
          description: Actor lacks ops:write.
  /v1/alerts/{alert_id}:
    get:
      tags:
        - Operations
      operationId: getAlertsAlertId
      summary: Get alert rule
      security:
        - bearerAuth: []
      parameters:
        - name: alert_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Alert rule.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlertRule"
    patch:
      tags:
        - Operations
      operationId: patchAlertsAlertId
      summary: Update alert rule
      security:
        - bearerAuth: []
      parameters:
        - name: alert_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateAlertRuleRequest"
      responses:
        "200":
          description: Alert rule updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlertRule"
    delete:
      tags:
        - Operations
      operationId: deleteAlertsAlertId
      summary: Disable alert rule
      description: Disables the rule and preserves historical firings.
      security:
        - bearerAuth: []
      parameters:
        - name: alert_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StateChangeRequest"
      responses:
        "200":
          description: Alert rule disabled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlertRule"
  /v1/alert-firings:
    get:
      tags:
        - Operations
      operationId: getAlertFirings
      summary: List alert firings
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Limit"
        - name: state
          in: query
          required: false
          schema:
            type: string
            enum: [open, acknowledged, resolved]
      responses:
        "200":
          description: Paginated alert firings.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlertFiringPage"
  /v1/alert-firings/{firing_id}:
    get:
      tags:
        - Operations
      operationId: getAlertFiringsFiringId
      summary: Get alert firing
      security:
        - bearerAuth: []
      parameters:
        - name: firing_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Alert firing.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlertFiring"
  /v1/alert-firings/{firing_id}:acknowledge:
    post:
      tags:
        - Operations
      operationId: postAlertFiringsFiringIdAcknowledge
      summary: Acknowledge alert firing
      security:
        - bearerAuth: []
      parameters:
        - name: firing_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StateChangeRequest"
      responses:
        "200":
          description: Alert firing acknowledged.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlertFiring"
  /v1/notification-channels:
    get:
      tags:
        - Signal Egress
      operationId: getNotificationChannels
      summary: List notification channels
      description: Lists tenant-scoped generic HTTPS webhook alert notification channels. Signing secrets are never returned.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Paginated notification channels.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationChannelPage"
    post:
      tags:
        - Signal Egress
      operationId: postNotificationChannels
      summary: Create notification channel
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateNotificationChannelRequest"
            example:
              name: "Ops webhook"
              channel_type: webhook
              url: "https://alerts.example.com/webhook"
              signing_secret: "<notification-signing-secret>"
      responses:
        "201":
          description: Notification channel created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationChannel"
              example:
                id: nch_example
                tenant_id: ten_example
                name: "Ops webhook"
                channel_type: webhook
                url: "https://alerts.example.com/webhook"
                state: active
                secret_hint: configured
                created_by: usr_example
                created_at: "2026-05-26T12:00:00Z"
                updated_at: "2026-05-26T12:00:00Z"
  /v1/notification-channels/{channel_id}:
    get:
      tags:
        - Signal Egress
      operationId: getNotificationChannelsChannelId
      summary: Get notification channel
      security:
        - bearerAuth: []
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Notification channel metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationChannel"
    patch:
      tags:
        - Signal Egress
      operationId: patchNotificationChannelsChannelId
      summary: Update notification channel
      security:
        - bearerAuth: []
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateNotificationChannelRequest"
      responses:
        "200":
          description: Notification channel updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationChannel"
    delete:
      tags:
        - Signal Egress
      operationId: deleteNotificationChannelsChannelId
      summary: Disable notification channel
      security:
        - bearerAuth: []
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StateChangeRequest"
      responses:
        "200":
          description: Notification channel disabled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationChannel"
  /v1/notification-channels/{channel_id}:test:
    post:
      tags:
        - Signal Egress
      operationId: postNotificationChannelsChannelIdTest
      summary: Queue a test notification delivery
      security:
        - bearerAuth: []
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StateChangeRequest"
      responses:
        "202":
          description: Test notification delivery queued.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationDelivery"
  /v1/notification-deliveries:
    get:
      tags:
        - Signal Egress
      operationId: getNotificationDeliveries
      summary: List notification deliveries
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Limit"
        - name: state
          in: query
          required: false
          schema:
            type: string
            enum: [scheduled, in_progress, succeeded, failed]
      responses:
        "200":
          description: Paginated notification deliveries.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationDeliveryPage"
  /v1/notification-deliveries/{delivery_id}/attempts:
    get:
      tags:
        - Signal Egress
      operationId: getNotificationDeliveriesDeliveryIdAttempts
      summary: List notification delivery attempts
      security:
        - bearerAuth: []
      parameters:
        - name: delivery_id
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Paginated notification delivery attempts.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationDeliveryAttemptPage"
  /v1/notification-deliveries/{delivery_id}:retry:
    post:
      tags:
        - Signal Egress
      operationId: postNotificationDeliveriesDeliveryIdRetry
      summary: Retry notification delivery
      security:
        - bearerAuth: []
      parameters:
        - name: delivery_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StateChangeRequest"
      responses:
        "200":
          description: Notification delivery rescheduled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationDelivery"
  /v1/siem-sinks:
    get:
      tags:
        - Signal Egress
      operationId: getSiemSinks
      summary: List SIEM sinks
      description: Lists tenant-scoped generic HTTPS audit-chain stream sinks. Signing secrets are never returned.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Paginated SIEM sinks.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SIEMSinkPage"
    post:
      tags:
        - Signal Egress
      operationId: postSiemSinks
      summary: Create SIEM sink
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSIEMSinkRequest"
            example:
              name: "Security log stream"
              sink_type: webhook
              url: "https://siem.example.com/ingest"
              signing_secret: "<siem-signing-secret>"
      responses:
        "201":
          description: SIEM sink created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SIEMSink"
              example:
                id: siem_example
                tenant_id: ten_example
                name: "Security log stream"
                sink_type: webhook
                url: "https://siem.example.com/ingest"
                state: active
                secret_hint: configured
                cursor_sequence: 0
                created_by: usr_example
                created_at: "2026-05-26T12:00:00Z"
                updated_at: "2026-05-26T12:00:00Z"
  /v1/siem-sinks/{sink_id}:
    get:
      tags:
        - Signal Egress
      operationId: getSiemSinksSinkId
      summary: Get SIEM sink
      security:
        - bearerAuth: []
      parameters:
        - name: sink_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: SIEM sink metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SIEMSink"
    patch:
      tags:
        - Signal Egress
      operationId: patchSiemSinksSinkId
      summary: Update SIEM sink
      security:
        - bearerAuth: []
      parameters:
        - name: sink_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateSIEMSinkRequest"
      responses:
        "200":
          description: SIEM sink updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SIEMSink"
    delete:
      tags:
        - Signal Egress
      operationId: deleteSiemSinksSinkId
      summary: Disable SIEM sink
      security:
        - bearerAuth: []
      parameters:
        - name: sink_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StateChangeRequest"
      responses:
        "200":
          description: SIEM sink disabled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SIEMSink"
  /v1/siem-sinks/{sink_id}:test:
    post:
      tags:
        - Signal Egress
      operationId: postSiemSinksSinkIdTest
      summary: Queue a test SIEM delivery
      security:
        - bearerAuth: []
      parameters:
        - name: sink_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StateChangeRequest"
      responses:
        "202":
          description: Test SIEM delivery queued.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SIEMDelivery"
  /v1/siem-deliveries:
    get:
      tags:
        - Signal Egress
      operationId: getSiemDeliveries
      summary: List SIEM deliveries
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Limit"
        - name: state
          in: query
          required: false
          schema:
            type: string
            enum: [scheduled, in_progress, succeeded, failed]
      responses:
        "200":
          description: Paginated SIEM deliveries.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SIEMDeliveryPage"
  /v1/siem-deliveries/{delivery_id}/attempts:
    get:
      tags:
        - Signal Egress
      operationId: getSiemDeliveriesDeliveryIdAttempts
      summary: List SIEM delivery attempts
      security:
        - bearerAuth: []
      parameters:
        - name: delivery_id
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Paginated SIEM delivery attempts.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SIEMDeliveryAttemptPage"
  /v1/siem-deliveries/{delivery_id}:retry:
    post:
      tags:
        - Signal Egress
      operationId: postSiemDeliveriesDeliveryIdRetry
      summary: Retry SIEM delivery
      security:
        - bearerAuth: []
      parameters:
        - name: delivery_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StateChangeRequest"
      responses:
        "200":
          description: SIEM delivery rescheduled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SIEMDelivery"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    basicAuth:
      type: http
      scheme: basic
    producerMTLS:
      type: mutualTLS
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
  responses:
    Problem:
      description: Problem details error response.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: about:blank
            title: Forbidden
            status: 403
            code: authorization_error
            stable_code: WEBHOOKERY_TENANT_ACCESS_DENIED
            request_id: req_example
            retryable: false
    ValidationProblem:
      description: The request is malformed or violates validation rules.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: about:blank
            title: Bad request
            status: 400
            code: validation_error
            stable_code: WEBHOOKERY_VALIDATION_FAILED
            detail: Invalid JSON body.
            request_id: req_example
            retryable: false
    UnauthorizedProblem:
      description: Authentication is missing, invalid, or expired.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: about:blank
            title: Unauthorized
            status: 401
            code: authentication_error
            stable_code: WEBHOOKERY_AUTHENTICATION_REQUIRED
            request_id: req_example
            retryable: false
    ForbiddenProblem:
      description: The authenticated actor lacks the required role, scope, tenant membership, or raw-payload permission.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: about:blank
            title: Forbidden
            status: 403
            code: authorization_error
            stable_code: WEBHOOKERY_TENANT_ACCESS_DENIED
            request_id: req_example
            retryable: false
    NotFoundProblem:
      description: The resource does not exist or is not visible to the actor.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: about:blank
            title: Not found
            status: 404
            code: not_found
            stable_code: WEBHOOKERY_RESOURCE_NOT_FOUND
            request_id: req_example
            retryable: false
    PayloadTooLargeProblem:
      description: The request body exceeds the configured capture limit.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: about:blank
            title: Payload too large
            status: 413
            code: payload_too_large
            stable_code: WEBHOOKERY_PAYLOAD_TOO_LARGE
            request_id: req_example
            retryable: false
    HeadersTooLargeProblem:
      description: Header count or header bytes exceed the configured ingress limits.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: about:blank
            title: Headers too large
            status: 431
            code: headers_too_large
            stable_code: WEBHOOKERY_HEADERS_TOO_LARGE
            request_id: req_example
            retryable: false
    StorageUnavailableProblem:
      description: Durable storage was unavailable before acknowledgement.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: about:blank
            title: Internal server error
            status: 503
            code: storage_unavailable
            stable_code: WEBHOOKERY_DURABLE_CAPTURE_UNAVAILABLE
            request_id: req_example
            retryable: true
  schemas:
    Problem:
      type: object
      required: [type, title, status, code, stable_code, request_id]
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        code:
          type: string
          description: Legacy short problem code retained for compatibility.
        stable_code:
          type: string
          description: Namespaced stable code for SDK, CLI, support, and incident handling.
          examples:
            - WEBHOOKERY_PROVIDER_SIGNATURE_INVALID
        request_id:
          type: string
        retryable:
          type: boolean
    DeliverySignature:
      type: string
      description: Webhook-Signature header using HMAC-SHA256.
    ReasonRequest:
      type: object
      required: [reason]
      additionalProperties: false
      properties:
        reason:
          type: string
          minLength: 1
          maxLength: 500
    CreateAPIKeyRequest:
      type: object
      required: [name, role, scopes]
      additionalProperties: false
      properties:
        name:
          type: string
        user_id:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
          enum: [owner, admin, developer, operator, security, auditor, support]
        scopes:
          type: array
          minItems: 1
          items:
            type: string
    APIKeyCreated:
      type: object
      required: [key, token]
      properties:
        key:
          $ref: "#/components/schemas/APIKey"
        token:
          type: string
          description: One-time API key token. It is not retrievable later.
    APIKey:
      type: object
      required: [id, tenant_id, user_id, name, prefix, last4, scopes, state, created_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        user_id:
          type: string
        name:
          type: string
        prefix:
          type: string
        last4:
          type: string
        scopes:
          type: array
          items:
            type: string
        state:
          type: string
          enum: [active, revoked]
        created_at:
          type: string
          format: date-time
        revoked_at:
          type: string
          format: date-time
    APIKeyPage:
      type: object
      required: [data, has_more]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/APIKey"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    OAuthClientCredentialsRequest:
      type: object
      required: [grant_type]
      additionalProperties: false
      properties:
        grant_type:
          type: string
          enum: [client_credentials]
        scope:
          type: string
          description: Optional requested scope string. The server issues only scopes allowed by the producer client.
    ProducerTokenResponse:
      type: object
      required: [access_token, token_type, expires_in, scope]
      properties:
        access_token:
          type: string
          description: Opaque bearer token returned once and stored hashed server-side.
        token_type:
          type: string
          enum: [Bearer]
        expires_in:
          type: integer
          minimum: 1
          maximum: 3600
        scope:
          type: string
    CreateProducerClientRequest:
      type: object
      required: [name]
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
        source_id:
          type: string
          description: Optional source binding. Bound clients may ingest only matching source_id events.
        scopes:
          type: array
          items:
            type: string
          default: [events:write]
        token_ttl_seconds:
          type: integer
          minimum: 60
          maximum: 3600
          default: 900
    UpdateProducerClientRequest:
      type: object
      required: [reason]
      additionalProperties: false
      properties:
        name:
          type: string
        source_id:
          type: string
        scopes:
          type: array
          items:
            type: string
        token_ttl_seconds:
          type: integer
          minimum: 60
          maximum: 3600
        state:
          type: string
          enum: [active, disabled]
        reason:
          type: string
          minLength: 1
          maxLength: 500
    ProducerClient:
      type: object
      required: [id, tenant_id, name, scopes, token_ttl_seconds, state, created_at, updated_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        name:
          type: string
        source_id:
          type: string
        scopes:
          type: array
          items:
            type: string
        token_ttl_seconds:
          type: integer
        state:
          type: string
          enum: [active, disabled]
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        disabled_at:
          type: string
          format: date-time
    ProducerClientCreated:
      type: object
      required: [client, client_secret]
      properties:
        client:
          $ref: "#/components/schemas/ProducerClient"
        client_secret:
          type: string
          description: One-time generated client secret. It is not retrievable later.
    ProducerClientSecret:
      type: object
      required: [id, tenant_id, client_id, prefix, last4, state, created_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        client_id:
          type: string
        prefix:
          type: string
        last4:
          type: string
        state:
          type: string
          enum: [active, revoked]
        created_at:
          type: string
          format: date-time
        last_used_at:
          type: string
          format: date-time
        revoked_at:
          type: string
          format: date-time
    ProducerClientSecretRotated:
      type: object
      required: [secret, client_secret]
      properties:
        secret:
          $ref: "#/components/schemas/ProducerClientSecret"
        client_secret:
          type: string
          description: One-time generated replacement secret. It is not retrievable later.
    ProducerClientPage:
      type: object
      required: [data, has_more]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/ProducerClient"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    CreateProducerMTLSIdentityRequest:
      type: object
      required: [name, certificate_pem]
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
        source_id:
          type: string
          description: Optional source binding for product-event ingestion.
        certificate_pem:
          type: string
          description: PEM-encoded public certificate. Private keys are never submitted.
    UpdateProducerMTLSIdentityRequest:
      type: object
      required: [reason]
      additionalProperties: false
      properties:
        name:
          type: string
        source_id:
          type: string
        state:
          type: string
          enum: [active, disabled]
        reason:
          type: string
          minLength: 1
          maxLength: 500
    VerifyProducerMTLSIdentityRequest:
      type: object
      required: [certificate_pem]
      additionalProperties: false
      properties:
        certificate_pem:
          type: string
    ProducerMTLSIdentity:
      type: object
      required: [id, tenant_id, name, certificate_fingerprint_sha256, cert_subject, not_before, not_after, state, created_at, updated_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        name:
          type: string
        source_id:
          type: string
        certificate_fingerprint_sha256:
          type: string
          description: SHA-256 fingerprint of the public certificate.
        cert_subject:
          type: string
        dns_sans:
          type: array
          items:
            type: string
        uri_sans:
          type: array
          items:
            type: string
        email_sans:
          type: array
          items:
            type: string
        not_before:
          type: string
          format: date-time
        not_after:
          type: string
          format: date-time
        state:
          type: string
          enum: [active, disabled]
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        disabled_at:
          type: string
          format: date-time
    ProducerMTLSIdentityVerification:
      type: object
      required: [matched]
      properties:
        matched:
          type: boolean
        identity:
          $ref: "#/components/schemas/ProducerMTLSIdentity"
    ProducerMTLSIdentityPage:
      type: object
      required: [data, has_more]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/ProducerMTLSIdentity"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    ProductEventIngestRequest:
      type: object
      required: [source_id]
      additionalProperties: true
      properties:
        id:
          type: string
          description: Producer-supplied event id.
        type:
          type: string
          description: Product event type.
        source_id:
          type: string
          description: Source identifier used for source-bound credential checks.
        data:
          type: object
          additionalProperties: true
          description: Product event payload.
    IdentityProvider:
      type: object
      required: [id, tenant_id, name, provider_type, issuer_url, client_id, state, created_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        name:
          type: string
        provider_type:
          type: string
          enum: [oidc]
        issuer_url:
          type: string
          format: uri
        authorization_endpoint:
          type: string
          format: uri
        token_endpoint:
          type: string
          format: uri
        jwks_uri:
          type: string
          format: uri
        client_id:
          type: string
        redirect_uri:
          type: string
          format: uri
        allowed_email_domains:
          type: array
          items:
            type: string
        state:
          type: string
          enum: [active, disabled]
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CreateIdentityProviderRequest:
      type: object
      required: [name, issuer_url, client_id, client_secret]
      additionalProperties: false
      properties:
        name:
          type: string
        provider_type:
          type: string
          enum: [oidc]
        issuer_url:
          type: string
          format: uri
        authorization_endpoint:
          type: string
          format: uri
        token_endpoint:
          type: string
          format: uri
        jwks_uri:
          type: string
          format: uri
        client_id:
          type: string
        client_secret:
          type: string
          writeOnly: true
        redirect_uri:
          type: string
          format: uri
        allowed_email_domains:
          type: array
          items:
            type: string
    UpdateIdentityProviderRequest:
      allOf:
        - $ref: "#/components/schemas/CreateIdentityProviderRequest"
        - type: object
          required: [reason]
          properties:
            state:
              type: string
              enum: [active, disabled]
            reason:
              type: string
    IdentityProviderPage:
      type: object
      required: [data, has_more]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/IdentityProvider"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    AuthSession:
      type: object
      required: [id, tenant_id, user_id, state, created_at, expires_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        user_id:
          type: string
        external_identity_id:
          type: string
        state:
          type: string
        created_at:
          type: string
          format: date-time
        last_seen_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
    AuthSessionPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/AuthSession"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    AuthSessionCreated:
      type: object
      properties:
        session:
          $ref: "#/components/schemas/AuthSession"
        actor:
          type: object
          additionalProperties: true
    CreateSCIMTokenRequest:
      type: object
      required: [name]
      additionalProperties: false
      properties:
        name:
          type: string
    SCIMToken:
      type: object
      required: [id, tenant_id, name, prefix, last4, state, created_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        name:
          type: string
        prefix:
          type: string
        last4:
          type: string
        state:
          type: string
        created_at:
          type: string
          format: date-time
        last_used_at:
          type: string
          format: date-time
        revoked_at:
          type: string
          format: date-time
    SCIMTokenCreated:
      type: object
      required: [token, value]
      properties:
        token:
          $ref: "#/components/schemas/SCIMToken"
        value:
          type: string
          description: One-time SCIM bearer token value.
    SCIMTokenPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/SCIMToken"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    SCIMUserRequest:
      type: object
      required: [userName]
      properties:
        id:
          type: string
        externalId:
          type: string
        userName:
          type: string
        displayName:
          type: string
        active:
          type: boolean
    SCIMGroupRequest:
      type: object
      required: [displayName]
      properties:
        id:
          type: string
        externalId:
          type: string
        displayName:
          type: string
        members:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              display:
                type: string
    SCIMPatchRequest:
      type: object
      required: [Operations]
      properties:
        Operations:
          type: array
          items:
            type: object
            required: [op]
            properties:
              op:
                type: string
              path:
                type: string
              value: {}
    RoleBinding:
      type: object
      properties:
        id:
          type: string
        tenant_id:
          type: string
        principal_type:
          type: string
          enum: [user, group]
        principal_id:
          type: string
        role:
          type: string
          enum: [owner, admin, developer, operator, security, auditor, support]
        resource_family:
          type: string
        resource_id:
          type: string
        environment:
          type: string
        state:
          type: string
    CreateRoleBindingRequest:
      type: object
      required: [principal_type, principal_id, role, resource_family, environment, reason]
      properties:
        principal_type:
          type: string
          enum: [user, group]
        principal_id:
          type: string
        role:
          type: string
        resource_family:
          type: string
        resource_id:
          type: string
        environment:
          type: string
        reason:
          type: string
    UpdateRoleBindingRequest:
      type: object
      required: [reason]
      properties:
        role:
          type: string
        resource_family:
          type: string
        resource_id:
          type: string
        environment:
          type: string
        state:
          type: string
        reason:
          type: string
    RoleBindingPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/RoleBinding"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    AccessPolicyRule:
      type: object
      properties:
        id:
          type: string
        tenant_id:
          type: string
        name:
          type: string
        action:
          type: string
        effect:
          type: string
          enum: [allow, deny]
        resource_family:
          type: string
        environment:
          type: string
        conditions:
          type: object
        state:
          type: string
    CreateAccessPolicyRuleRequest:
      type: object
      required: [name, action, effect, resource_family, environment, reason]
      properties:
        name:
          type: string
        action:
          type: string
        effect:
          type: string
          enum: [allow, deny]
        resource_family:
          type: string
        environment:
          type: string
        conditions:
          type: object
        reason:
          type: string
    UpdateAccessPolicyRuleRequest:
      type: object
      required: [reason]
      properties:
        name:
          type: string
        action:
          type: string
        effect:
          type: string
          enum: [allow, deny]
        resource_family:
          type: string
        environment:
          type: string
        conditions:
          type: object
        state:
          type: string
        reason:
          type: string
    AccessPolicyRulePage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/AccessPolicyRule"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    AuthzExplainRequest:
      type: object
      required: [action, resource_family]
      properties:
        actor_id:
          type: string
        action:
          type: string
        resource_family:
          type: string
        resource_id:
          type: string
        environment:
          type: string
        attributes:
          type: object
          additionalProperties:
            type: string
    AuthzDecision:
      type: object
      properties:
        allowed:
          type: boolean
        action:
          type: string
        reason:
          type: string
        matched_role:
          type: string
        matched_role_binding_id:
          type: string
        matched_policy_rule_id:
          type: string
    Source:
      type: object
      required: [id, tenant_id, name, provider, adapter, state]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        name:
          type: string
        provider:
          type: string
        adapter:
          type: string
        state:
          type: string
          enum: [active, disabled]
    SourcePage:
      type: object
      required: [data, has_more]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Source"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    CreateSourceRequest:
      type: object
      required: [name, provider]
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
        provider:
          type: string
          minLength: 1
        adapter:
          type: string
        verification_secret:
          type: string
          description: Required except for internal trusted producer sources. Never returned.
    UpdateSourceRequest:
      type: object
      required: [reason]
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
        state:
          type: string
          enum: [active, disabled]
        reason:
          type: string
          minLength: 1
    RotateSourceSecretRequest:
      type: object
      required: [new_secret, reason]
      additionalProperties: false
      properties:
        new_secret:
          type: string
          minLength: 1
        grace_period_hours:
          type: integer
          minimum: 0
          maximum: 720
          default: 72
        reason:
          type: string
          minLength: 1
    RotateEndpointSecretRequest:
      type: object
      required: [reason]
      additionalProperties: false
      properties:
        grace_period_hours:
          type: integer
          minimum: 0
          maximum: 720
          default: 72
        reason:
          type: string
          minLength: 1
    CreateEndpointRequest:
      type: object
      required: [url]
      additionalProperties: false
      properties:
        name:
          type: string
        url:
          type: string
          format: uri
        retry_policy_id:
          type: string
        mtls_client_cert_pem:
          type: string
          description: PEM client certificate. Required with mtls_client_key_pem and never returned by the API.
        mtls_client_key_pem:
          type: string
          description: PEM client private key. Required with mtls_client_cert_pem, encrypted at rest, and never returned by the API.
    UpdateEndpointRequest:
      type: object
      required: [reason]
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
        url:
          type: string
          format: uri
        state:
          type: string
          enum: [active, disabled]
        retry_policy_id:
          type: string
          description: Optional retry policy reference. Use an empty string to clear an existing policy.
        reason:
          type: string
          minLength: 1
    Endpoint:
      type: object
      required: [id, tenant_id, name, url, state, mtls_enabled, created_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        name:
          type: string
        url:
          type: string
          format: uri
        state:
          type: string
        retry_policy_id:
          type: string
        mtls_enabled:
          type: boolean
        mtls_cert_subject:
          type: string
          description: Subject metadata from the configured client certificate. Private key material is never returned.
        created_at:
          type: string
          format: date-time
    EndpointPage:
      type: object
      required: [data, has_more]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Endpoint"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    SourceSecretVersion:
      type: object
      properties:
        id:
          type: string
        tenant_id:
          type: string
        source_id:
          type: string
        version:
          type: integer
        state:
          type: string
          enum: [active, previous, revoked]
        active_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
        revoked_at:
          type: string
          format: date-time
    EndpointSecretVersion:
      type: object
      properties:
        id:
          type: string
        tenant_id:
          type: string
        endpoint_id:
          type: string
        version:
          type: integer
        algorithm:
          type: string
          enum: [hmac_sha256]
        state:
          type: string
          enum: [active, previous, revoked]
        active_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
        revoked_at:
          type: string
          format: date-time
    CreateSubscriptionRequest:
      type: object
      required: [endpoint_id, event_types]
      additionalProperties: false
      properties:
        endpoint_id:
          type: string
        event_types:
          type: array
          items:
            type: string
        payload_format:
          type: string
          default: canonical_json
        transformation_id:
          type: string
          description: Optional active transformation to snapshot onto new delivery payloads.
    UpdateSubscriptionRequest:
      type: object
      required: [reason]
      additionalProperties: false
      properties:
        endpoint_id:
          type: string
        event_types:
          type: array
          items:
            type: string
          minItems: 1
        payload_format:
          type: string
        transformation_id:
          type: string
          description: Optional active transformation. Use an empty string to clear an existing transformation.
        state:
          type: string
          enum: [active, disabled]
        reason:
          type: string
          minLength: 1
    Subscription:
      type: object
      required: [id, tenant_id, endpoint_id, event_types, payload_format, state, version, created_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        endpoint_id:
          type: string
        event_types:
          type: array
          items:
            type: string
        payload_format:
          type: string
        transformation_id:
          type: string
        transformation_version_id:
          type: string
        state:
          type: string
          enum: [active, disabled]
        version:
          type: integer
        active_version_id:
          type: string
        created_at:
          type: string
          format: date-time
    SubscriptionPage:
      type: object
      required: [data, has_more]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Subscription"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    CreateRouteRequest:
      type: object
      required: [source_id, name, endpoint_id]
      additionalProperties: false
      properties:
        source_id:
          type: string
        name:
          type: string
        priority:
          type: integer
          default: 100
        event_types:
          type: array
          items:
            type: string
        endpoint_id:
          type: string
        retry_policy_id:
          type: string
        transformation_id:
          type: string
          description: Optional active transformation to snapshot onto new delivery payloads.
        state:
          type: string
          enum: [draft, active, inactive]
          default: draft
    UpdateRouteRequest:
      type: object
      required: [reason]
      additionalProperties: false
      properties:
        source_id:
          type: string
        name:
          type: string
          minLength: 1
        priority:
          type: integer
          minimum: 0
        event_types:
          type: array
          items:
            type: string
          minItems: 1
        endpoint_id:
          type: string
        retry_policy_id:
          type: string
          description: Optional retry policy reference. Use an empty string to clear an existing policy.
        transformation_id:
          type: string
          description: Optional active transformation. Use an empty string to clear an existing transformation.
        state:
          type: string
          enum: [draft, active, inactive]
        reason:
          type: string
          minLength: 1
    Route:
      type: object
      required: [id, tenant_id, source_id, name, priority, event_types, endpoint_id, state, version, created_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        source_id:
          type: string
        name:
          type: string
        priority:
          type: integer
        event_types:
          type: array
          items:
            type: string
        endpoint_id:
          type: string
        state:
          type: string
          enum: [draft, active, inactive]
        version:
          type: integer
        active_version_id:
          type: string
        retry_policy_id:
          type: string
        transformation_id:
          type: string
        transformation_version_id:
          type: string
        created_at:
          type: string
          format: date-time
    RoutePage:
      type: object
      required: [data, has_more]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Route"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    StateChangeRequest:
      type: object
      required: [reason]
      additionalProperties: false
      properties:
        reason:
          type: string
          minLength: 1
    CreateEventTypeRequest:
      type: object
      required: [name]
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
        description:
          type: string
    UpdateEventTypeRequest:
      type: object
      required: [reason]
      additionalProperties: false
      properties:
        description:
          type: string
        state:
          type: string
          enum: [active, disabled]
        reason:
          type: string
          minLength: 1
    EventType:
      type: object
      required: [name, tenant_id, description, state, created_at]
      properties:
        name:
          type: string
        tenant_id:
          type: string
        description:
          type: string
        state:
          type: string
          enum: [active, disabled]
        created_at:
          type: string
          format: date-time
    EventTypePage:
      type: object
      required: [data, has_more]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/EventType"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    CreateEventSchemaRequest:
      type: object
      required: [version, schema]
      additionalProperties: false
      properties:
        version:
          type: string
          minLength: 1
        schema:
          type: string
          minLength: 1
    UpdateEventSchemaRequest:
      type: object
      required: [state, reason]
      additionalProperties: false
      properties:
        state:
          type: string
          enum: [active, deprecated, retired]
        reason:
          type: string
          minLength: 1
    EventSchema:
      type: object
      required: [id, tenant_id, event_type, version, schema, state, created_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        event_type:
          type: string
        version:
          type: string
        schema:
          type: string
        state:
          type: string
          enum: [active, deprecated, retired]
        created_at:
          type: string
          format: date-time
    EventSchemaPage:
      type: object
      required: [data, has_more]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/EventSchema"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    CreateIncidentRequest:
      type: object
      required: [title, reason]
      additionalProperties: false
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
        reason:
          type: string
          minLength: 1
          maxLength: 500
    AddIncidentEventRequest:
      type: object
      required: [event_id, reason]
      additionalProperties: false
      properties:
        event_id:
          type: string
          minLength: 1
        reason:
          type: string
          minLength: 1
          maxLength: 500
    IncidentReportRequest:
      type: object
      required: [reason]
      additionalProperties: false
      properties:
        reason:
          type: string
          minLength: 1
          maxLength: 500
    CreateIncidentEvidenceExportRequest:
      type: object
      required: [reason]
      additionalProperties: false
      properties:
        reason:
          type: string
          minLength: 1
          maxLength: 500
    Incident:
      type: object
      required: [id, tenant_id, title, reason, state, created_by, created_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        title:
          type: string
        reason:
          type: string
        state:
          type: string
          enum: [active, disabled]
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    IncidentPage:
      type: object
      required: [data, has_more]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Incident"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    IncidentEvent:
      type: object
      required: [id, tenant_id, incident_id, event_id, added_by, reason, created_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        incident_id:
          type: string
        event_id:
          type: string
        added_by:
          type: string
        reason:
          type: string
        created_at:
          type: string
          format: date-time
    IncidentReportSnapshot:
      type: object
      required: [id, tenant_id, incident_id, schema_version, report, markdown, generated_by, generated_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        incident_id:
          type: string
        schema_version:
          type: string
          enum: [webhookery.incident_report.v1]
        report:
          type: object
          additionalProperties: true
          description: Machine-readable incident report. Raw payload bodies, secrets, and signatures are omitted by default.
        markdown:
          type: string
          description: Human-readable Markdown incident report.
        generated_by:
          type: string
        generated_at:
          type: string
          format: date-time
    EventTimelineEntry:
      type: object
      required: [schema_version, sequence, kind, ref_id, state, detail, occurred_at]
      additionalProperties: false
      properties:
        schema_version:
          type: string
          enum: [webhookery.event_timeline.v1]
        sequence:
          type: integer
          minimum: 1
        kind:
          type: string
          enum: [event, receipt, raw_payload, normalized, delivery, delivery_payload, attempt, reconciliation, replay, audit]
        ref_id:
          type: string
        state:
          type: string
        detail:
          type: string
          description: Redacted timeline detail; raw bodies and secrets are not included.
        occurred_at:
          type: string
          format: date-time
    EventTimelinePage:
      type: object
      required: [data, next_cursor, has_more]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/EventTimelineEntry"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    Event:
      type: object
      required: [id, tenant_id, source_id, provider, type, raw_payload_id, raw_payload_hash, signature_verified, verification_reason, deduplication_key, dedupe_status, received_at, trace_id]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        source_id:
          type: string
        provider:
          type: string
        type:
          type: string
        provider_event_id:
          type: string
        raw_payload_id:
          type: string
        raw_payload_hash:
          type: string
        signature_verified:
          type: boolean
        verification_reason:
          type: string
        deduplication_key:
          type: string
        dedupe_status:
          type: string
        received_at:
          type: string
          format: date-time
        trace_id:
          type: string
    EventPage:
      type: object
      required: [data, next_cursor, has_more]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Event"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    NormalizedEnvelope:
      type: object
      required: [id, tenant_id, event_id, provider, type, source, envelope_sha256, data_sha256, metadata_sha256, storage_status, created_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        event_id:
          type: string
        adapter_version_id:
          type: string
        provider:
          type: string
        provider_event_id:
          type: string
        type:
          type: string
        source:
          type: string
        subject:
          type: string
        envelope:
          type: object
          additionalProperties: true
          description: Included only when include_data=true and the body has not been retained.
        data:
          type: object
          additionalProperties: true
          description: Included only when include_data=true and the body has not been retained.
        metadata:
          type: object
          additionalProperties: true
        envelope_sha256:
          type: string
        data_sha256:
          type: string
        metadata_sha256:
          type: string
        storage_status:
          type: string
          enum: [stored, deleted, metadata_only]
        storage_deleted_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    CreateTransformationRequest:
      type: object
      required: [name]
      additionalProperties: false
      properties:
        name:
          type: string
        operations:
          type: array
          description: JSON Pointer operations. Supported op values are set, copy, drop, and redact.
          items:
            $ref: "#/components/schemas/TransformationOperation"
    CreateTransformationVersionRequest:
      type: object
      required: [operations]
      additionalProperties: false
      properties:
        operations:
          type: array
          items:
            $ref: "#/components/schemas/TransformationOperation"
    TransformationOperation:
      type: object
      required: [op, path]
      additionalProperties: false
      properties:
        op:
          type: string
          enum: [set, copy, drop, redact]
        path:
          type: string
          description: JSON Pointer path.
        from:
          type: string
          description: JSON Pointer source path for copy.
        value:
          description: Value used by set.
    Transformation:
      type: object
      required: [id, tenant_id, name, state, created_by, created_at, updated_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        name:
          type: string
        state:
          type: string
          enum: [active, disabled]
        active_version_id:
          type: string
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    TransformationVersion:
      type: object
      required: [id, tenant_id, transformation_id, version, config_hash, operations, state, created_by, created_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        transformation_id:
          type: string
        version:
          type: integer
        config_hash:
          type: string
        operations:
          type: array
          items:
            $ref: "#/components/schemas/TransformationOperation"
        state:
          type: string
          enum: [draft, active, inactive]
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
    TransformationPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Transformation"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    TransformationVersionPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/TransformationVersion"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    CreateProviderConnectionRequest:
      type: object
      required: [name, provider, credential]
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
        provider:
          type: string
          enum: [stripe, github, shopify, slack]
        credential_type:
          type: string
          enum: [api_key, bearer_token]
          default: api_key
        credential:
          type: string
          minLength: 1
          writeOnly: true
        config:
          type: object
          additionalProperties:
            type: string
          description: Provider-specific settings such as `source_id`, GitHub `owner`, `repo`, and `hook_id`, or test `base_url`.
    ProviderConnection:
      type: object
      properties:
        id:
          type: string
        tenant_id:
          type: string
        name:
          type: string
        provider:
          type: string
          enum: [stripe, github, shopify, slack]
        state:
          type: string
          enum: [active, revoked]
        credential_type:
          type: string
        credential_hint:
          type: string
        config:
          type: object
          additionalProperties:
            type: string
        verified_at:
          type: string
          format: date-time
        revoked_at:
          type: string
          format: date-time
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ProviderConnectionPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/ProviderConnection"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    CreateProviderAdapterRequest:
      type: object
      required: [name, kind]
      additionalProperties: false
      properties:
        name:
          type: string
          pattern: "^[a-z0-9_-]+$"
        kind:
          type: string
          enum: [declarative, plugin]
        description:
          type: string
        risk_level:
          type: string
          enum: [low, medium, high]
        provenance_url:
          type: string
          format: uri
    ProviderAdapter:
      type: object
      properties:
        id:
          type: string
        tenant_id:
          type: string
        name:
          type: string
        kind:
          type: string
          enum: [builtin, declarative, plugin]
        description:
          type: string
        risk_level:
          type: string
        state:
          type: string
          enum: [draft, active, deprecated, retired, disabled]
        provenance_url:
          type: string
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ProviderAdapterPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/ProviderAdapter"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    CreateAdapterVersionRequest:
      type: object
      required: [version, reason]
      additionalProperties: false
      properties:
        version:
          type: string
        definition:
          type: object
          description: Declarative adapter definition. Must not contain secrets or bearer tokens.
        package_sha256:
          type: string
        package_signature:
          type: string
        sbom_sha256:
          type: string
        provenance_url:
          type: string
        risk_level:
          type: string
          enum: [low, medium, high]
        reason:
          type: string
    AdapterVersion:
      type: object
      properties:
        id:
          type: string
        tenant_id:
          type: string
        adapter_id:
          type: string
        name:
          type: string
        version:
          type: string
        kind:
          type: string
          enum: [builtin, declarative, plugin]
        config_hash:
          type: string
        definition:
          type: object
        definition_sha256:
          type: string
        package_sha256:
          type: string
        package_signature:
          type: string
        sbom_sha256:
          type: string
        provenance_url:
          type: string
        risk_level:
          type: string
        test_results:
          type: array
          items: {}
        review_notes:
          type: string
        state:
          type: string
          enum: [draft, automated_tests, security_review, staging_approved, active, deprecated, retired]
        created_by:
          type: string
        reviewed_by:
          type: string
        activated_by:
          type: string
        created_at:
          type: string
          format: date-time
        reviewed_at:
          type: string
          format: date-time
        activated_at:
          type: string
          format: date-time
    AdapterVersionPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/AdapterVersion"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    CreateAdapterTestVectorRequest:
      type: object
      required: [name, request, expected]
      additionalProperties: false
      properties:
        name:
          type: string
        purpose:
          type: string
        request:
          type: object
        expected:
          type: object
    AdapterTestVector:
      type: object
      properties:
        id:
          type: string
        tenant_id:
          type: string
        adapter_version_id:
          type: string
        name:
          type: string
        purpose:
          type: string
        request_sha256:
          type: string
        expected_sha256:
          type: string
        state:
          type: string
    AdapterVersionTransitionRequest:
      type: object
      required: [action, reason]
      additionalProperties: false
      properties:
        action:
          type: string
          enum: [submit_tests, request_review, approve_staging, activate, deprecate, retire]
        reason:
          type: string
        test_results:
          type: array
          items: {}
        review_notes:
          type: string
    ReconciliationJobRequest:
      type: object
      required: [connection_id]
      additionalProperties: false
      properties:
        connection_id:
          type: string
        dry_run:
          type: boolean
          default: false
        capture_missing:
          type: boolean
          default: false
        route_recovered:
          type: boolean
          default: false
          description: Requires `capture_missing=true`; recovered provider API events route only when explicitly enabled.
        redeliver_failed:
          type: boolean
          default: false
        scope_object_id:
          type: string
        window_start:
          type: string
          format: date-time
        window_end:
          type: string
          format: date-time
        reason:
          type: string
    ReconciliationJob:
      type: object
      properties:
        id:
          type: string
        tenant_id:
          type: string
        connection_id:
          type: string
        provider:
          type: string
        state:
          type: string
          enum: [scheduled, running, completed, canceled, failed]
        dry_run:
          type: boolean
        capture_missing:
          type: boolean
        route_recovered:
          type: boolean
        redeliver_failed:
          type: boolean
        scope_object_id:
          type: string
        window_start:
          type: string
          format: date-time
        window_end:
          type: string
          format: date-time
        cursor:
          type: string
        reason:
          type: string
        total_items:
          type: integer
        matched_items:
          type: integer
        missing_items:
          type: integer
        captured_items:
          type: integer
        redelivered_items:
          type: integer
        unrecoverable_items:
          type: integer
        failed_items:
          type: integer
        error:
          type: string
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        canceled_at:
          type: string
          format: date-time
    ReconciliationJobPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/ReconciliationJob"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    ReconciliationItem:
      type: object
      properties:
        id:
          type: string
        tenant_id:
          type: string
        job_id:
          type: string
        provider:
          type: string
        provider_object_id:
          type: string
        provider_object_type:
          type: string
        outcome:
          type: string
          enum: [matched, missing, captured, redelivery_requested, unrecoverable, failed]
        local_event_id:
          type: string
        recovered_event_id:
          type: string
        provider_api_evidence_id:
          type: string
        redelivery_requested:
          type: boolean
        error:
          type: string
        metadata:
          type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ReconciliationItemPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/ReconciliationItem"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    CreateRetryPolicyRequest:
      type: object
      required: [name, max_attempts, max_duration_seconds, initial_delay_seconds, max_delay_seconds]
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
        max_attempts:
          type: integer
          minimum: 1
          maximum: 100
        max_duration_seconds:
          type: integer
          minimum: 1
          maximum: 2592000
        initial_delay_seconds:
          type: integer
          minimum: 1
        max_delay_seconds:
          type: integer
          minimum: 1
          maximum: 86400
        rate_limit_per_minute:
          type: integer
          minimum: 0
          maximum: 60000
        state:
          type: string
          enum: [active, disabled]
          default: active
    UpdateRetryPolicyRequest:
      type: object
      required: [reason]
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
        max_attempts:
          type: integer
          minimum: 1
          maximum: 100
        max_duration_seconds:
          type: integer
          minimum: 1
          maximum: 2592000
        initial_delay_seconds:
          type: integer
          minimum: 1
        max_delay_seconds:
          type: integer
          minimum: 1
          maximum: 86400
        rate_limit_per_minute:
          type: integer
          minimum: 0
          maximum: 60000
        state:
          type: string
          enum: [active, disabled]
        reason:
          type: string
          minLength: 1
    RetryPolicy:
      type: object
      properties:
        id:
          type: string
        tenant_id:
          type: string
        name:
          type: string
        version:
          type: integer
        state:
          type: string
          enum: [active, disabled]
        max_attempts:
          type: integer
        max_duration_seconds:
          type: integer
        initial_delay_seconds:
          type: integer
        max_delay_seconds:
          type: integer
        rate_limit_per_minute:
          type: integer
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
    RetryPolicyPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/RetryPolicy"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    RouteVersion:
      type: object
      properties:
        id:
          type: string
        tenant_id:
          type: string
        route_id:
          type: string
        version:
          type: integer
        config_hash:
          type: string
        source_id:
          type: string
        name:
          type: string
        priority:
          type: integer
        event_types:
          type: array
          items:
            type: string
        endpoint_id:
          type: string
        retry_policy_id:
          type: string
        transformation_id:
          type: string
        transformation_version_id:
          type: string
        state:
          type: string
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
    RouteVersionPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/RouteVersion"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    ValidateSchemaRequest:
      type: object
      required: [payload]
      additionalProperties: false
      properties:
        payload:
          type: string
          description: JSON payload to validate.
    CheckSchemaCompatibilityRequest:
      type: object
      required: [new_schema]
      additionalProperties: false
      properties:
        new_schema:
          type: string
          description: Candidate JSON Schema document.
    SchemaValidationResult:
      type: object
      properties:
        valid:
          type: boolean
        errors:
          type: array
          items:
            type: string
    SchemaCompatibilityResult:
      type: object
      properties:
        compatible:
          type: boolean
        errors:
          type: array
          items:
            type: string
    DeadLetterReleaseRequest:
      type: object
      required: [reason_code, reason]
      additionalProperties: false
      properties:
        reason_code:
          type: string
          enum: [receiver_fixed, provider_reconciliation, operator_requested, support_investigation, customer_dispute, test_drill, incident_recovery]
        reason:
          type: string
          minLength: 1
    DeadLetterBulkReleaseRequest:
      type: object
      required: [reason_code, reason]
      additionalProperties: false
      properties:
        entry_ids:
          type: array
          description: Empty or omitted means up to 100 currently open entries.
          items:
            type: string
        reason_code:
          type: string
          enum: [receiver_fixed, provider_reconciliation, operator_requested, support_investigation, customer_dispute, test_drill, incident_recovery]
        reason:
          type: string
          minLength: 1
    ReplayRequest:
      type: object
      required: [reason_code, reason]
      additionalProperties: false
      properties:
        event_id:
          type: string
        delivery_id:
          type: string
        endpoint_id:
          type: string
        reason_code:
          type: string
          enum: [receiver_fixed, provider_reconciliation, operator_requested, support_investigation, customer_dispute, test_drill, incident_recovery]
        reason:
          type: string
          minLength: 1
        dry_run:
          type: boolean
        config_mode:
          type: string
          enum: [current, original]
          default: current
        rate_limit_per_minute:
          type: integer
          minimum: 0
          maximum: 60000
        require_approval:
          type: boolean
          default: false
          description: Create the replay job in pending_approval state. Delivery work is not enqueued until the job is approved.
        approval_expires_at:
          type: string
          format: date-time
          description: Optional approval expiry for pending replay jobs. When omitted with require_approval=true, the server defaults to 24 hours from creation. The field is rejected unless require_approval is true.
    CreateReplayApprovalPolicyRequest:
      type: object
      required: [scope_type, reason]
      additionalProperties: false
      properties:
        scope_type:
          type: string
          enum: [tenant, source, route]
        scope_id:
          type: string
          description: Required for source and route policies. Omit for tenant-wide policies.
        require_approval:
          type: boolean
          default: true
          description: Active v1 policies require approval. Disable the policy to stop automatic approval gating.
        default_expiry_seconds:
          type: integer
          minimum: 300
          maximum: 604800
          default: 86400
        reason:
          type: string
          minLength: 1
          maxLength: 500
    ReplayApprovalPolicy:
      type: object
      required: [id, tenant_id, scope_type, require_approval, default_expiry_seconds, state, created_by, created_at, updated_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        scope_type:
          type: string
          enum: [tenant, source, route]
        scope_id:
          type: string
        require_approval:
          type: boolean
        default_expiry_seconds:
          type: integer
        state:
          type: string
        reason:
          type: string
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ReplayApprovalPolicyPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/ReplayApprovalPolicy"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    CreateAuditExportRequest:
      type: object
      additionalProperties: false
      properties:
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
        include_raw_payloads:
          type: boolean
          default: false
        include_payload_bodies:
          type: boolean
          default: false
        include_timelines:
          type: boolean
          default: false
        reason:
          type: string
          maxLength: 500
    AuditChainVerifyRequest:
      type: object
      additionalProperties: false
      properties:
        from_sequence:
          type: integer
          minimum: 0
        to_sequence:
          type: integer
          minimum: 0
    AuditChainAnchorRequest:
      type: object
      required: [reason]
      additionalProperties: false
      properties:
        from_sequence:
          type: integer
          minimum: 0
        to_sequence:
          type: integer
          minimum: 0
        reason:
          type: string
          minLength: 1
          maxLength: 500
    AuditChainHead:
      type: object
      required: [tenant_id, sequence, chain_hash, unchained_events]
      properties:
        tenant_id:
          type: string
        sequence:
          type: integer
        chain_hash:
          type: string
        last_audit_event_id:
          type: string
        unchained_events:
          type: integer
        last_anchored_at:
          type: string
          format: date-time
        last_anchor_id:
          type: string
        last_anchor_sequence:
          type: integer
        updated_at:
          type: string
          format: date-time
    AuditChainVerification:
      type: object
      required: [tenant_id, valid, from_sequence, to_sequence, checked_entries, retained_entries, failures, verified_at]
      properties:
        tenant_id:
          type: string
        valid:
          type: boolean
        from_sequence:
          type: integer
        to_sequence:
          type: integer
        checked_entries:
          type: integer
        retained_entries:
          type: integer
        start_chain_hash:
          type: string
        end_chain_hash:
          type: string
        failures:
          type: array
          items:
            $ref: "#/components/schemas/AuditChainFailure"
        verified_at:
          type: string
          format: date-time
    AuditChainFailure:
      type: object
      required: [sequence, kind]
      properties:
        sequence:
          type: integer
        audit_event_id:
          type: string
        kind:
          type: string
          enum: [missing_previous_entry, missing_entry, unsupported_canonicalization_version, previous_hash_mismatch, missing_audit_event, event_hash_mismatch, chain_hash_mismatch]
        detail:
          type: string
    AuditChainAnchor:
      type: object
      required: [id, tenant_id, from_sequence, to_sequence, chain_hash, manifest_sha256, storage_backend, created_by, reason, created_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        from_sequence:
          type: integer
        to_sequence:
          type: integer
        chain_hash:
          type: string
        manifest_sha256:
          type: string
        storage_backend:
          type: string
          enum: [postgres, s3]
        object_bucket:
          type: string
        object_key:
          type: string
        created_by:
          type: string
        reason:
          type: string
        created_at:
          type: string
          format: date-time
    AuditChainAnchorPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/AuditChainAnchor"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    EvidenceExport:
      type: object
      required: [id, tenant_id, state, include_raw_payloads, include_timelines, include_payload_bodies, format, storage_backend, sha256, manifest_sha256, size_bytes, created_by, created_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        state:
          type: string
          enum: [ready, failed]
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
        include_raw_payloads:
          type: boolean
        include_timelines:
          type: boolean
        include_payload_bodies:
          type: boolean
        format:
          type: string
          enum: [tar+gzip+jsonl]
        storage_backend:
          type: string
          enum: [postgres, s3]
        object_bucket:
          type: string
        object_key:
          type: string
        sha256:
          type: string
          description: SHA-256 of the downloadable bundle.
        manifest_sha256:
          type: string
          description: SHA-256 of manifest.json inside the bundle.
        size_bytes:
          type: integer
        error:
          type: string
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
    EvidenceExportPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/EvidenceExport"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    CreateRetentionPolicyRequest:
      type: object
      required: [resource_type, retention_days]
      additionalProperties: false
      properties:
        resource_type:
          type: string
          enum: [raw_payload, normalized_envelope_data, delivery_payload, provider_api_evidence, audit_event]
        source_id:
          type: string
          description: Optional source filter for raw payload policies.
        retention_days:
          type: integer
          minimum: 1
          maximum: 3650
        state:
          type: string
          enum: [active, disabled]
          default: active
    UpdateRetentionPolicyRequest:
      type: object
      additionalProperties: false
      properties:
        source_id:
          type: string
        retention_days:
          type: integer
          minimum: 1
          maximum: 3650
        state:
          type: string
          enum: [active, disabled]
    RetentionPolicy:
      type: object
      required: [id, tenant_id, resource_type, retention_days, state, legal_hold, created_by, created_at, updated_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        resource_type:
          type: string
          enum: [raw_payload, normalized_envelope_data, delivery_payload, provider_api_evidence, audit_event]
        source_id:
          type: string
        retention_days:
          type: integer
        state:
          type: string
          enum: [active, disabled]
        legal_hold:
          type: boolean
        hold_reason:
          type: string
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    RetentionPolicyPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/RetentionPolicy"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    EndpointHealth:
      type: object
      properties:
        endpoint_id:
          type: string
        tenant_id:
          type: string
        url:
          type: string
        state:
          type: string
        circuit_state:
          type: string
          enum: [closed, open]
        failure_count:
          type: integer
        disabled_until:
          type: string
          format: date-time
        last_attempt_at:
          type: string
          format: date-time
        last_status:
          type: integer
        last_failure:
          type: string
        successes_24h:
          type: integer
        failures_24h:
          type: integer
    EndpointHealthPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/EndpointHealth"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    WorkerStatus:
      type: object
      required: [worker_id, state, last_seen_at, expires_at]
      properties:
        worker_id:
          type: string
        state:
          type: string
          enum: [active, expired]
        last_seen_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
    WorkerStatusPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/WorkerStatus"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    QueueStats:
      type: object
      required: [name, pending, in_progress, completed, terminal, due_now, oldest_pending_age_seconds]
      properties:
        name:
          type: string
        tenant_id:
          type: string
        pending:
          type: integer
        in_progress:
          type: integer
        completed:
          type: integer
        terminal:
          type: integer
        due_now:
          type: integer
        oldest_pending_age_seconds:
          type: integer
        next_available_at:
          type: string
          format: date-time
    QueueStatsPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/QueueStats"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    OpsMetrics:
      type: object
      required: [events_total, outbox_pending, dead_letter_open, quarantine_open, audit_chain_unchained_events, audit_chain_verification_failures, audit_chain_last_anchor_age_seconds, deliveries_by_state, replay_jobs_by_state]
      properties:
        events_total:
          type: integer
        outbox_pending:
          type: integer
        oldest_outbox_age_seconds:
          type: integer
        dead_letter_open:
          type: integer
        quarantine_open:
          type: integer
        endpoint_circuit_open:
          type: integer
        audit_chain_unchained_events:
          type: integer
          description: Aggregate count of audit events that do not yet have chain entries.
        audit_chain_verification_failures:
          type: integer
          description: Aggregate count of non-retained chain entries whose audit rows are missing.
        audit_chain_last_anchor_age_seconds:
          type: integer
          description: Age of the newest audit chain anchor in seconds, or zero when no anchors exist.
        deliveries_by_state:
          type: object
          additionalProperties:
            type: integer
        replay_jobs_by_state:
          type: object
          additionalProperties:
            type: integer
        reconciliation_jobs_by_state:
          type: object
          additionalProperties:
            type: integer
        reconciliation_items_by_outcome:
          type: object
          additionalProperties:
            type: integer
    MetricRollup:
      type: object
      required: [id, tenant_id, metric_name, bucket_start, bucket_seconds, dimensions_hash, value, source, created_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        metric_name:
          type: string
        bucket_start:
          type: string
          format: date-time
        bucket_seconds:
          type: integer
        dimensions:
          type: object
          additionalProperties:
            type: string
        dimensions_hash:
          type: string
        value:
          type: number
        source:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    MetricRollupPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/MetricRollup"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    AlertRule:
      type: object
      required: [id, tenant_id, name, rule_type, metric_name, threshold, comparator, window_seconds, state, created_by, created_at, updated_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        name:
          type: string
        rule_type:
          type: string
          enum: [dead_letter_open, quarantine_open, endpoint_failure_rate_24h, endpoint_circuit_open, oldest_outbox_age_seconds, worker_lease_expired, audit_chain_verification_failures, reconciliation_failed_items]
        metric_name:
          type: string
        threshold:
          type: number
        comparator:
          type: string
          enum: [">", ">=", "<", "<=", "=="]
        window_seconds:
          type: integer
        dimensions:
          type: object
          additionalProperties:
            type: string
        state:
          type: string
          enum: [active, disabled]
        channel_ids:
          type: array
          items:
            type: string
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CreateAlertRuleRequest:
      type: object
      required: [name, rule_type, threshold]
      properties:
        name:
          type: string
        rule_type:
          type: string
          enum: [dead_letter_open, quarantine_open, endpoint_failure_rate_24h, endpoint_circuit_open, oldest_outbox_age_seconds, worker_lease_expired, audit_chain_verification_failures, reconciliation_failed_items]
        metric_name:
          type: string
        threshold:
          type: number
        comparator:
          type: string
          enum: [">", ">=", "<", "<=", "=="]
        window_seconds:
          type: integer
        dimensions:
          type: object
          additionalProperties:
            type: string
        state:
          type: string
          enum: [active, disabled]
        channel_ids:
          type: array
          items:
            type: string
    UpdateAlertRuleRequest:
      type: object
      required: [reason]
      properties:
        name:
          type: string
        threshold:
          type: number
        comparator:
          type: string
          enum: [">", ">=", "<", "<=", "=="]
        window_seconds:
          type: integer
        dimensions:
          type: object
          additionalProperties:
            type: string
        state:
          type: string
          enum: [active, disabled]
        channel_ids:
          type: array
          items:
            type: string
        reason:
          type: string
    AlertRulePage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/AlertRule"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    AlertFiring:
      type: object
      required: [id, tenant_id, rule_id, state, observed_value, threshold, started_at, last_evaluated_at, updated_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        rule_id:
          type: string
        state:
          type: string
          enum: [open, acknowledged, resolved]
        observed_value:
          type: number
        threshold:
          type: number
        reason:
          type: string
        started_at:
          type: string
          format: date-time
        last_evaluated_at:
          type: string
          format: date-time
        acknowledged_by:
          type: string
        acknowledged_at:
          type: string
          format: date-time
        resolved_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    AlertFiringPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/AlertFiring"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    NotificationChannel:
      type: object
      required: [id, tenant_id, name, channel_type, url, state, secret_hint, created_by, created_at, updated_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        name:
          type: string
        channel_type:
          type: string
          enum: [webhook]
        url:
          type: string
          format: uri
        state:
          type: string
          enum: [active, disabled]
        secret_hint:
          type: string
          description: Non-sensitive metadata only; the signing secret is never returned.
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CreateNotificationChannelRequest:
      type: object
      required: [name, url, signing_secret]
      properties:
        name:
          type: string
        channel_type:
          type: string
          enum: [webhook]
        url:
          type: string
          format: uri
        signing_secret:
          type: string
          writeOnly: true
          minLength: 16
    UpdateNotificationChannelRequest:
      type: object
      required: [reason]
      properties:
        name:
          type: string
        url:
          type: string
          format: uri
        signing_secret:
          type: string
          writeOnly: true
          minLength: 16
        state:
          type: string
          enum: [active, disabled]
        reason:
          type: string
    NotificationChannelPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/NotificationChannel"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    NotificationDelivery:
      type: object
      required: [id, tenant_id, channel_id, transition, state, body_sha256, attempt_count, created_at, updated_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        channel_id:
          type: string
        firing_id:
          type: string
        transition:
          type: string
          enum: [open, acknowledged, resolved, test]
        state:
          type: string
          enum: [scheduled, in_progress, succeeded, failed]
        body_sha256:
          type: string
        attempt_count:
          type: integer
        next_attempt_at:
          type: string
          format: date-time
        last_attempt_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    NotificationDeliveryPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/NotificationDelivery"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    NotificationDeliveryAttempt:
      type: object
      required: [id, tenant_id, delivery_id, status_code, failure_class, response_truncated, created_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        delivery_id:
          type: string
        status_code:
          type: integer
        failure_class:
          type: string
        response_body:
          type: string
        response_truncated:
          type: boolean
        error:
          type: string
        created_at:
          type: string
          format: date-time
    NotificationDeliveryAttemptPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/NotificationDeliveryAttempt"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    SIEMSink:
      type: object
      required: [id, tenant_id, name, sink_type, url, state, secret_hint, cursor_sequence, created_by, created_at, updated_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        name:
          type: string
        sink_type:
          type: string
          enum: [webhook]
        url:
          type: string
          format: uri
        state:
          type: string
          enum: [active, disabled]
        secret_hint:
          type: string
          description: Non-sensitive metadata only; the signing secret is never returned.
        cursor_sequence:
          type: integer
          format: int64
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CreateSIEMSinkRequest:
      type: object
      required: [name, url, signing_secret]
      properties:
        name:
          type: string
        sink_type:
          type: string
          enum: [webhook]
        url:
          type: string
          format: uri
        signing_secret:
          type: string
          writeOnly: true
          minLength: 16
    UpdateSIEMSinkRequest:
      type: object
      required: [reason]
      properties:
        name:
          type: string
        url:
          type: string
          format: uri
        signing_secret:
          type: string
          writeOnly: true
          minLength: 16
        state:
          type: string
          enum: [active, disabled]
        reason:
          type: string
    SIEMSinkPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/SIEMSink"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    SIEMDelivery:
      type: object
      required: [id, tenant_id, sink_id, from_sequence, to_sequence, state, body_sha256, attempt_count, created_at, updated_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        sink_id:
          type: string
        from_sequence:
          type: integer
          format: int64
        to_sequence:
          type: integer
          format: int64
        state:
          type: string
          enum: [scheduled, in_progress, succeeded, failed]
        body_sha256:
          type: string
        attempt_count:
          type: integer
        next_attempt_at:
          type: string
          format: date-time
        last_attempt_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    SIEMDeliveryPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/SIEMDelivery"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    SIEMDeliveryAttempt:
      type: object
      required: [id, tenant_id, delivery_id, status_code, failure_class, response_truncated, created_at]
      properties:
        id:
          type: string
        tenant_id:
          type: string
        delivery_id:
          type: string
        status_code:
          type: integer
        failure_class:
          type: string
        response_body:
          type: string
        response_truncated:
          type: boolean
        error:
          type: string
        created_at:
          type: string
          format: date-time
    SIEMDeliveryAttemptPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/SIEMDeliveryAttempt"
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    OpsStorageStatus:
      type: object
      required: [raw_storage_mode, object_storage_configured, raw_payloads_by_status, raw_payloads_by_backend, raw_payload_stored_bytes]
      properties:
        tenant_id:
          type: string
        raw_storage_mode:
          type: string
          enum: [postgres, s3]
        object_storage_configured:
          type: boolean
        raw_payloads_by_status:
          type: object
          additionalProperties:
            type: integer
        raw_payloads_by_backend:
          type: object
          additionalProperties:
            type: integer
        raw_payload_stored_bytes:
          type: integer
        normalized_envelopes_by_status:
          type: object
          additionalProperties:
            type: integer
        delivery_payloads_by_status:
          type: object
          additionalProperties:
            type: integer
        provider_api_evidence_by_status:
          type: object
          additionalProperties:
            type: integer
        evidence_exports_by_state:
          type: object
          additionalProperties:
            type: integer
        evidence_exports_by_backend:
          type: object
          additionalProperties:
            type: integer
    OpsConfig:
      type: object
      required: [environment, ui_enabled, raw_storage_mode, object_storage_configured, secret_box_mode, key_custody_configured, max_ingress_body_bytes, max_header_bytes, max_header_pairs, max_header_value_bytes]
      properties:
        environment:
          type: string
        ui_enabled:
          type: boolean
        raw_storage_mode:
          type: string
          enum: [postgres, s3]
        object_storage_configured:
          type: boolean
        secret_box_mode:
          type: string
          enum: [local, vault-transit, aws-kms]
        key_custody_configured:
          type: boolean
        key_custody_key_ref:
          type: string
          description: Redacted key reference, such as a short hash, when an external custody key is configured.
        max_ingress_body_bytes:
          type: integer
        max_header_bytes:
          type: integer
        max_header_pairs:
          type: integer
        max_header_value_bytes:
          type: integer