openapi.yaml

openapi: 3.0.0
info:
  title: PgBeam Control Plane API
  description: |
    REST API for the PgBeam multi-tenant PostgreSQL proxy platform.
    Manages projects, database connections, cache/pool configuration, and regions.
  version: 1.0.0
  license:
    name: Proprietary
    url: https://pgbeam.com/terms
  contact:
    name: PgBeam
    url: https://pgbeam.com
servers:
  - url: https://api.pgbeam.com
    description: Production
security:
  - BearerAuth: []
  - ApiKeyAuth: []
tags:
  - name: Projects
    description: Project lifecycle, custom domains, read replicas, and cache rules
    x-icon: FolderKanban
  - name: Databases
    description: Database connection management per project
    x-icon: Database
  - name: Policies
    description: Policy profiles enforced on agent credentials
    x-icon: ShieldCheck
  - name: Agents
    description: Scoped agent credentials for AI agent database access
    x-icon: Bot
  - name: Approvals
    description: Human approval workflow for held agent statements
    x-icon: CircleCheck
  - name: Webhooks
    description: Event delivery endpoints for project audit and anomaly events
    x-icon: Webhook
  - name: Honeytokens
    description: Decoy (canary) relations that trip on agent access
    x-icon: Fingerprint
  - name: SchemaAnnotations
    description: Human-written table and column descriptions for the schema catalog
    x-icon: BookText
  - name: Anomalies
    description: Anomalous-behavior alerts surfaced by the gateway
    x-icon: TriangleAlert
  - name: Branches
    description: Ephemeral sandbox branches for write isolation
    x-icon: GitBranch
  - name: Migrations
    description: Migration safety linting for schema changes
    x-icon: FileCog
  - name: Analytics
    description: Usage metrics, billing data, and query insights
    x-icon: ChartLine
  - name: Platform
    description: Regions and health checks
    x-icon: Globe
  - name: Account
    description: Account data, privacy controls, and onboarding
    x-icon: CircleUser
  - name: Support
    description: Support case management
    x-icon: LifeBuoy
  - name: Internal
    description: Internal service-to-service endpoints
  - name: MCP
    description: Model Context Protocol (MCP) remote server endpoint
    x-sdk-exclude:
      - go
      - ts
paths:
  /v1/account/export:
    get:
      operationId: exportAccountData
      summary: Export account data
      description: >-
        Returns all personal data associated with the authenticated user in a structured JSON format. Supports GDPR data
        portability and CCPA right to know. Audit logs are limited to the most recent 1000 entries.
      tags:
        - Account
      responses:
        '200':
          description: Account data export.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountExport'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/agents:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: createAgentCredential
      x-feature-flag: agent-gateway
      summary: Create an agent credential
      description: >-
        Issues a scoped Postgres login and hosted MCP token for an AI agent. The connection string and MCP token are
        returned once and cannot be retrieved again.
      tags:
        - Agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentCredentialRequest'
      responses:
        '201':
          description: Agent credential created. Secrets shown once.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCredentialSecrets'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Agent credential quota reached for the organization plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    get:
      operationId: listAgentCredentials
      x-feature-flag: agent-gateway
      summary: List agent credentials
      description: Lists agent credentials for the project. Secrets are never returned.
      tags:
        - Agents
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: List of agent credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAgentCredentialsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/agents/{agent_id}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/AgentId'
    get:
      operationId: getAgentCredential
      x-feature-flag: agent-gateway
      summary: Get an agent credential
      description: Returns a single agent credential. Secrets are never included.
      tags:
        - Agents
      responses:
        '200':
          description: The agent credential (no secrets).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCredential'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateAgentCredentialStatus
      x-feature-flag: agent-gateway
      summary: Enable or disable an agent credential
      description: Toggles the kill-switch. Disabling drops live connections within seconds.
      tags:
        - Agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentCredentialStatusRequest'
      responses:
        '200':
          description: Updated agent credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCredential'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: revokeAgentCredential
      x-feature-flag: agent-gateway
      summary: Revoke an agent credential
      description: Permanently revokes the credential and drops any live connections.
      tags:
        - Agents
      responses:
        '204':
          description: Agent credential revoked.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/projects/{project_id}/agents/{agent_id}/rotate:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/AgentId'
    post:
      operationId: rotateAgentCredential
      x-feature-flag: agent-gateway
      summary: Rotate an agent credential's secrets
      description: >-
        Generates a new Postgres password and MCP token for the credential in place, keeping the same id, username,
        name, and policy. Live connections using the old password are dropped within seconds. The new secrets are
        returned once and cannot be retrieved again.
      tags:
        - Agents
      responses:
        '200':
          description: Secrets rotated. New secrets shown once.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCredentialSecrets'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The credential is revoked and cannot be rotated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/projects/{project_id}/agents/{agent_id}/policy-recommendation:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/AgentId'
    post:
      operationId: recommendAgentPolicy
      x-feature-flag: agent-gateway
      summary: Recommend a least-privilege policy from recorded traffic
      description: >-
        Derives the tightest policy that would still pass every statement this agent credential has legitimately run,
        using its recorded audit history over a lookback window (default 30 days). The candidate's table allowlist is
        the union of relations actually referenced, its statement-kind allow set is the observed set, it downgrades to
        read-only when no writes were seen, and its max_rows ceiling comes from an observed high-percentile row count.
        The candidate is proven safe by replaying it through the data plane's own policy engine against the same
        history: a good recommendation has replay.summary.newly_blocked == 0. This endpoint is advisory only. It reads
        the audit log, never connects to the upstream database, and never creates, updates, or mutates any policy or
        credential; the operator loads the candidate into the editor and saves it themselves.
      tags:
        - Policies
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyRecommendationInput'
      responses:
        '200':
          description: The recommended candidate policy and its replay proof.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyRecommendation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/anomalies:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: listAnomalyAlerts
      x-feature-flag: agent-gateway
      summary: List anomaly alerts
      description: Lists anomaly alerts for the project, newest first, optionally filtered by status.
      tags:
        - Anomalies
      parameters:
        - name: status
          in: query
          required: false
          description: Filter to a single status.
          schema:
            type: string
            enum:
              - open
              - acknowledged
              - resolved
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Page of anomaly alerts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAnomalyAlertsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/anomalies/{anomaly_id}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/AnomalyId'
    patch:
      operationId: updateAnomalyAlert
      x-feature-flag: agent-gateway
      summary: Triage an anomaly alert
      description: Updates the triage status of an anomaly alert (acknowledge or resolve).
      tags:
        - Anomalies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAnomalyAlertRequest'
      responses:
        '200':
          description: The updated anomaly alert.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnomalyAlert'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/projects/{project_id}/approvals:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: listApprovalRequests
      x-feature-flag: agent-gateway
      summary: List approval requests
      description: Lists approval requests for the project, newest first, optionally filtered by status.
      tags:
        - Approvals
      parameters:
        - name: status
          in: query
          required: false
          description: Filter to a single status.
          schema:
            type: string
            enum:
              - pending
              - approved
              - rejected
              - expired
              - executed
              - failed
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Page of approval requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListApprovalRequestsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/approvals/{approval_id}/approve:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ApprovalId'
    post:
      operationId: approveApprovalRequest
      x-feature-flag: agent-gateway
      summary: Approve a held statement
      description: Approves a pending approval request, releasing the held statement.
      tags:
        - Approvals
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApprovalDecisionRequest'
      responses:
        '200':
          description: The updated approval request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovalRequest'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
  /v1/projects/{project_id}/approvals/{approval_id}/reject:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ApprovalId'
    post:
      operationId: rejectApprovalRequest
      x-feature-flag: agent-gateway
      summary: Reject a held statement
      description: Rejects a pending approval request, denying the held statement.
      tags:
        - Approvals
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApprovalDecisionRequest'
      responses:
        '200':
          description: The updated approval request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovalRequest'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
  /v1/projects/{project_id}/audit-logs:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: listAuditLogs
      x-feature-flag: agent-gateway
      summary: List agent audit logs
      description: >-
        Returns agent statement audit entries for the project, newest first, with optional credential, event, decision,
        source and date-range filters.
      tags:
        - Agents
      parameters:
        - $ref: '#/components/parameters/AuditCredentialId'
        - $ref: '#/components/parameters/AuditEvent'
        - $ref: '#/components/parameters/AuditDecision'
        - $ref: '#/components/parameters/AuditSource'
        - $ref: '#/components/parameters/AuditStart'
        - $ref: '#/components/parameters/AuditEnd'
        - name: before
          in: query
          required: false
          description: Return entries strictly older than this timestamp (keyset pagination cursor).
          schema:
            type: string
            format: date-time
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Page of audit entries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAuditLogsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/audit-logs/export:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: exportAuditLogs
      x-feature-flag: agent-gateway
      summary: Export agent audit logs as CSV
      description: >-
        Streams the project's agent audit entries as a CSV file, newest first, honoring the same credential, event,
        decision, source and date-range filters as the list endpoint. The full filtered set is streamed (no pagination);
        the result is suitable for spreadsheets, SIEM ingestion, and compliance archives.
      tags:
        - Agents
      parameters:
        - $ref: '#/components/parameters/AuditCredentialId'
        - $ref: '#/components/parameters/AuditEvent'
        - $ref: '#/components/parameters/AuditDecision'
        - $ref: '#/components/parameters/AuditSource'
        - $ref: '#/components/parameters/AuditStart'
        - $ref: '#/components/parameters/AuditEnd'
      responses:
        '200':
          description: CSV stream of filtered audit entries.
          content:
            text/csv:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/audit-logs/verify:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: verifyAuditChain
      x-feature-flag: agent-gateway
      summary: Verify the tamper-evident audit chain
      description: >-
        Recomputes the project's audit hash chain over an optional time range and reports whether it is intact. Each
        audit entry is linked to its predecessor with a SHA-256 hash, so editing or deleting any row breaks the chain.
        On a break, the response reports the first sequence number where a tampered or deleted entry was detected.
        Requires the same audit:read permission as the list and export endpoints.
      tags:
        - Agents
      parameters:
        - $ref: '#/components/parameters/AuditStart'
        - $ref: '#/components/parameters/AuditEnd'
      responses:
        '200':
          description: Chain verification result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditChainVerification'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/plans:
    get:
      operationId: listPlans
      summary: List available plans
      description: Returns all available plan tiers with their limits and pricing.
      tags:
        - Analytics
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      responses:
        '200':
          description: List of available plans.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPlansResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/organizations/{org_id}/plan:
    get:
      operationId: getOrganizationPlan
      summary: Get organization plan
      description: Returns the current plan and limits for the organization.
      tags:
        - Analytics
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OrgId'
      responses:
        '200':
          description: Organization plan details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationPlan'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/organizations/{org_id}/vercel-installation:
    get:
      operationId: getVercelInstallation
      summary: Get Vercel Marketplace installation status
      description: |
        Returns the Vercel Marketplace installation for the organization,
        including its provisioned resources and their current-period usage.
        Returns 404 when the organization was not provisioned through the
        Vercel Marketplace. Powers the dashboard's Vercel integration page.
      tags:
        - Analytics
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OrgId'
      responses:
        '200':
          description: Vercel installation status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VercelInstallationStatus'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/organizations/{org_id}/spend-limit:
    put:
      operationId: updateSpendLimit
      summary: Update spend limit
      description: Sets the monthly spend limit for an organization. Null removes the limit.
      tags:
        - Analytics
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OrgId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSpendLimitRequest'
      responses:
        '200':
          description: Spend limit updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationPlan'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/organizations/{org_id}/cancellation-feedback:
    post:
      operationId: submitCancellationFeedback
      summary: Submit cancellation feedback
      description: Records optional feedback when a user cancels their subscription.
      tags:
        - Analytics
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OrgId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancellationFeedbackRequest'
      responses:
        '204':
          description: Feedback recorded.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/branches:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: listDatabaseBranches
      x-feature-flag: agent-gateway
      summary: List sandbox branches
      description: Lists ephemeral sandbox branches for the project's databases.
      tags:
        - Branches
      parameters:
        - name: status
          in: query
          required: false
          description: Filter to a single status.
          schema:
            type: string
            enum:
              - pending
              - ready
              - error
              - discarded
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Page of sandbox branches.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDatabaseBranchesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/branches/{branch_id}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/BranchId'
    delete:
      operationId: discardDatabaseBranch
      x-feature-flag: agent-gateway
      summary: Discard a sandbox branch
      description: Marks an ephemeral sandbox branch as discarded for teardown.
      tags:
        - Branches
      responses:
        '204':
          description: Sandbox branch discarded.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/projects/{project_id}/databases/{database_id}/cache-rules:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/DatabaseId'
    get:
      operationId: listCacheRules
      summary: List cache rules
      description: |
        Returns the cache rules for a database, showing all observed query
        shapes with their stats and cache recommendations.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Cache rule entries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCacheRulesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/databases/{database_id}/cache-rules/{query_hash}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/DatabaseId'
      - name: query_hash
        in: path
        required: true
        description: xxhash64 hex of the normalized SQL.
        schema:
          type: string
          pattern: ^[a-f0-9]+$
          minLength: 16
          maxLength: 16
    put:
      operationId: updateCacheRule
      summary: Update cache rule
      description: |
        Enable or disable caching for a specific query shape, with optional
        TTL and SWR overrides. Requires the query to exist in the cache rules.
      tags:
        - Projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCacheRuleRequest'
      responses:
        '200':
          description: Cache rule updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateCacheRuleResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/databases:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: createDatabase
      summary: Add a database
      description: Registers a new upstream PostgreSQL database for the project.
      tags:
        - Databases
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDatabaseRequest'
      responses:
        '201':
          description: Database created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Database'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    get:
      operationId: listDatabases
      summary: List databases
      description: Lists all databases registered for the project.
      tags:
        - Databases
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: List of databases.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDatabasesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/databases/{database_id}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/DatabaseId'
    get:
      operationId: getDatabase
      summary: Get a database
      description: Returns a single database by ID.
      tags:
        - Databases
      responses:
        '200':
          description: Database found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Database'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    patch:
      operationId: updateDatabase
      summary: Update a database
      description: Partially updates a database connection. Only provided fields are modified.
      tags:
        - Databases
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDatabaseRequest'
      responses:
        '200':
          description: Database updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Database'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      operationId: deleteDatabase
      summary: Delete a database
      description: Removes a database registration from the project.
      tags:
        - Databases
      responses:
        '204':
          description: Database deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/databases/{database_id}/test-connection:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/DatabaseId'
    post:
      operationId: testDatabaseConnection
      summary: Test database connection
      description: Attempts to connect to the upstream database using the stored credentials and returns the result.
      tags:
        - Databases
      responses:
        '200':
          description: Connection test result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestConnectionResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/databases/{database_id}/scan-pii:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/DatabaseId'
    post:
      operationId: scanDatabaseForPii
      x-feature-flag: agent-gateway
      summary: Scan a database for likely-PII columns
      description: >-
        Connects to the upstream database read-only, inspects information_schema and samples column values against PII
        heuristics, and returns ranked masking suggestions. Suggestions are advisory — the operator reviews them and
        applies the ones they want into a policy profile's masking rules. Nothing is auto-applied.
      tags:
        - Databases
      responses:
        '200':
          description: PII scan result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanPiiResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/databases/{database_id}/schema-catalog:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/DatabaseId'
    get:
      operationId: getSchemaCatalog
      x-feature-flag: agent-gateway
      summary: Read a database's schema catalog
      description: >-
        Connects to the upstream database read-only and returns its user relations (tables and views) and columns.
        Powers table/column autocomplete and view-aware warnings in the policy editor — relation kind distinguishes a
        view (whose masking/row-filters apply to the view itself, not its base tables) from a base table, and a
        per-column is_binary flag flags columns that mask to NULL. System schemas are excluded; nothing is persisted.
      tags:
        - Databases
      responses:
        '200':
          description: Schema catalog.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaCatalog'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/domains:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: createCustomDomain
      x-feature-flag: custom-domains
      summary: Add a custom domain
      description: >-
        Registers a new custom domain for the project. Returns DNS verification instructions. Requires a Scale or
        Enterprise plan.
      tags:
        - Projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomDomainRequest'
      responses:
        '201':
          description: Custom domain created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDomain'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Custom domains require a Scale or Enterprise plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    get:
      operationId: listCustomDomains
      x-feature-flag: custom-domains
      summary: List custom domains
      description: Lists all custom domains registered for the project.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: List of custom domains.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCustomDomainsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/domains/{domain_id}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/DomainId'
    delete:
      operationId: deleteCustomDomain
      x-feature-flag: custom-domains
      summary: Delete a custom domain
      description: Removes a custom domain from the project and revokes its TLS certificate.
      tags:
        - Projects
      responses:
        '204':
          description: Custom domain deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/domains/{domain_id}/verify:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/DomainId'
    post:
      operationId: verifyCustomDomain
      x-feature-flag: custom-domains
      summary: Verify custom domain DNS
      description: >-
        Checks DNS TXT record to verify domain ownership. Updates domain status on success. Requires a Scale or
        Enterprise plan.
      tags:
        - Projects
      responses:
        '200':
          description: Verification result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyCustomDomainResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Custom domains require a Scale or Enterprise plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/health:
    get:
      operationId: getHealth
      summary: Health check
      description: Returns the health status of the API server.
      tags:
        - Platform
      security: []
      responses:
        '200':
          description: Service is healthy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/honeytokens:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: createHoneytoken
      summary: Register a honeytoken
      description: |
        Registers a decoy (canary) relation for the project. Any agent statement
        that references it is blocked and recorded as a canary_tripped audit event.
      tags:
        - Honeytokens
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HoneytokenInput'
      responses:
        '201':
          description: Honeytoken registered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Honeytoken'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    get:
      operationId: listHoneytokens
      summary: List honeytokens
      description: Lists the project's honeytokens.
      tags:
        - Honeytokens
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: List of honeytokens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListHoneytokensResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/honeytokens/{honeytoken_id}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/HoneytokenId'
    get:
      operationId: getHoneytoken
      summary: Get a honeytoken
      description: Returns a single honeytoken by ID.
      tags:
        - Honeytokens
      responses:
        '200':
          description: The honeytoken.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Honeytoken'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateHoneytoken
      summary: Update a honeytoken
      description: Updates a honeytoken's relation or action.
      tags:
        - Honeytokens
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HoneytokenInput'
      responses:
        '200':
          description: Updated honeytoken.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Honeytoken'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteHoneytoken
      summary: Delete a honeytoken
      description: Removes a honeytoken from the project.
      tags:
        - Honeytokens
      responses:
        '204':
          description: Honeytoken deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/projects/{project_id}/insights:
    get:
      operationId: getProjectInsights
      summary: Get query insights for a project
      description: |
        Returns aggregated query-level analytics for a project including top queries
        by count, cache hit/miss summary, and latency statistics.
      tags:
        - Analytics
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: range
          in: query
          required: false
          description: Time range to query. Defaults to 24h.
          schema:
            type: string
            enum:
              - 1h
              - 6h
              - 24h
              - 7d
            default: 24h
            example: 24h
        - name: limit
          in: query
          required: false
          description: Maximum number of top queries to return (1-100).
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Query insights for the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectInsights'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/mcp:
    post:
      operationId: mcpTransport
      summary: MCP server (Streamable HTTP)
      description: >-
        Model Context Protocol endpoint using the Streamable HTTP transport. Accepts JSON-RPC 2.0 requests and exposes
        every public API operation as an MCP tool. Use this with any MCP-compatible client (Claude Code, Cursor,
        Windsurf, custom agents) to let AI assistants manage PgBeam resources.


        **Transport:** Streamable HTTP (MCP spec 2025-03-26)

        **Protocol:** JSON-RPC 2.0

        **Methods:** `initialize`, `tools/list`, `tools/call`, `ping`


        Prefer the CLI (`pgbeam mcp`) for local stdio transport. Use this endpoint for remote or server-to-server MCP
        integration.
      tags:
        - MCP
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpRequest'
            examples:
              initialize:
                summary: Initialize session
                value:
                  jsonrpc: '2.0'
                  id: '1'
                  method: initialize
                  params:
                    protocolVersion: '2025-03-26'
                    capabilities: {}
                    clientInfo:
                      name: my-agent
                      version: 1.0.0
              tools_list:
                summary: List available tools
                value:
                  jsonrpc: '2.0'
                  id: '2'
                  method: tools/list
              tools_call:
                summary: Call a tool
                value:
                  jsonrpc: '2.0'
                  id: '3'
                  method: tools/call
                  params:
                    name: listProjects
                    arguments:
                      org_id: org_abc123
      responses:
        '200':
          description: JSON-RPC 2.0 response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/migrations:lint:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: lintMigration
      x-feature-flag: agent-gateway
      summary: Lint a migration
      description: Analyzes a migration script for unsafe schema changes and returns findings.
      tags:
        - Migrations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MigrationLintRequest'
      responses:
        '200':
          description: Lint results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MigrationLintResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/organizations/{org_id}/onboarding:
    parameters:
      - $ref: '#/components/parameters/OrgId'
    get:
      operationId: getOnboardingProgress
      summary: Get onboarding progress
      description: Returns the onboarding checklist progress for an organization.
      tags:
        - Account
      responses:
        '200':
          description: Onboarding progress.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingProgress'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    patch:
      operationId: updateOnboardingProgress
      summary: Update onboarding progress
      description: Mark an onboarding step as complete or dismiss the checklist.
      tags:
        - Account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOnboardingRequest'
      responses:
        '200':
          description: Updated onboarding progress.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingProgress'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/organizations:
    get:
      operationId: listOrganizations
      summary: List organizations
      description: >-
        Lists the organizations visible to the caller's credential. An organization-scoped API key (pbo_) returns
        exactly the organization it belongs to. A user credential (account-scoped API key or dashboard session token)
        returns the organizations the user is a member of, including the caller's role in each.
      tags:
        - Account
      responses:
        '200':
          description: Organizations visible to the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOrganizationsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/policies:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: createPolicyProfile
      x-feature-flag: agent-gateway
      summary: Create a policy profile
      description: Creates a policy profile that can be attached to agent credentials.
      tags:
        - Policies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyProfileInput'
      responses:
        '201':
          description: Policy profile created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyProfile'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    get:
      operationId: listPolicyProfiles
      x-feature-flag: agent-gateway
      summary: List policy profiles
      description: Lists all policy profiles for the project.
      tags:
        - Policies
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: List of policy profiles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPolicyProfilesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/policies/{policy_id}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/PolicyId'
    get:
      operationId: getPolicyProfile
      x-feature-flag: agent-gateway
      summary: Get a policy profile
      description: Returns a single policy profile by ID.
      tags:
        - Policies
      responses:
        '200':
          description: The policy profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyProfile'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updatePolicyProfile
      x-feature-flag: agent-gateway
      summary: Update a policy profile
      description: Updates a policy profile. Changes hot-reload to active agent sessions.
      tags:
        - Policies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyProfileInput'
      responses:
        '200':
          description: Updated policy profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyProfile'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      operationId: deletePolicyProfile
      x-feature-flag: agent-gateway
      summary: Delete a policy profile
      description: Deletes a policy profile. Fails if agent credentials still reference it.
      tags:
        - Policies
      responses:
        '204':
          description: Policy profile deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Policy profile is still referenced by agent credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/projects/{project_id}/policy-evaluations:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: dryEvalPolicy
      x-feature-flag: agent-gateway
      summary: Dry-eval a policy against a SQL statement
      description: >-
        Evaluates a single SQL statement against a policy (either a draft policy supplied inline or an existing policy
        referenced by id) and returns the decision the proxy would make: allow, block, mask, or row-filter. The
        evaluation reuses the data plane's own policy engine (the same parser, allow/block rules, row-filter rewriter,
        and masking analysis enforced on live agent sessions), so a what-if verdict matches real enforcement. Stateful
        checks a single-statement preview cannot model (per-region query and egress budgets, human approvals, and
        rollback/sandbox write routing) are reported as informational notes, not verdicts. This is a pure compute
        endpoint; it does not connect to the upstream database and persists nothing.
      tags:
        - Policies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DryEvalInput'
      responses:
        '200':
          description: The dry-eval decision.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DryEvalResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/policy-replays:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: replayPolicy
      x-feature-flag: agent-gateway
      summary: Replay recorded agent traffic against a policy
      description: >-
        Replays the project's recorded agent audit traffic against a candidate policy (either a draft supplied inline or
        an existing policy referenced by id) and reports what would change: which queries that ran would now be blocked,
        which blocked queries would now be permitted, and which results would be masked or row-filtered. Traffic is
        deduplicated by normalized query shape, newest first, and every statement is evaluated through the data plane's
        own policy engine, so the verdicts match real enforcement. Stateful checks (budgets, approvals, write-mode
        routing) are reported as informational notes on each result, not verdicts. This endpoint reads only the audit
        log; it never connects to the upstream database and persists nothing.
      tags:
        - Policies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyReplayInput'
      responses:
        '200':
          description: The replay summary and per-query decisions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyReplayResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects:
    post:
      operationId: createProject
      summary: Create a project
      description: Creates a new project within the specified organization.
      tags:
        - Projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '201':
          description: Project created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateProjectResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    get:
      operationId: listProjects
      summary: List projects
      description: Lists projects filtered by organization. Requires org_id query parameter.
      tags:
        - Projects
      parameters:
        - name: org_id
          in: query
          required: true
          description: Organization ID to filter projects.
          schema:
            type: string
            pattern: ^[\x20-\x7E]+$
            example: org_abc123
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
        - name: sort_by
          in: query
          required: false
          description: Sort field for projects list.
          schema:
            type: string
            enum:
              - name
              - created_at
              - active_connections
            default: created_at
            example: created_at
      responses:
        '200':
          description: List of projects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListProjectsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getProject
      summary: Get a project
      description: Returns a single project by ID.
      tags:
        - Projects
      responses:
        '200':
          description: Project found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    patch:
      operationId: updateProject
      summary: Update a project
      description: Partially updates a project. Only provided fields are modified.
      tags:
        - Projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProjectRequest'
      responses:
        '200':
          description: Project updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      operationId: deleteProject
      summary: Delete a project
      description: Soft-deletes a project and all associated databases.
      tags:
        - Projects
      responses:
        '204':
          description: Project deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/metrics:
    get:
      operationId: getProjectMetrics
      summary: Get project metrics
      description: Returns recent project metrics snapshots, optionally filtered by region.
      tags:
        - Projects
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: limit
          in: query
          required: false
          description: Maximum number of recent snapshots to return.
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 60
        - name: region
          in: query
          required: false
          description: Filter metrics by region code.
          schema:
            type: string
            example: us-east-1
      responses:
        '200':
          description: Metrics snapshots
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectMetricsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/regions:
    get:
      operationId: listRegions
      summary: List available regions
      description: Returns all active data plane regions.
      tags:
        - Platform
      responses:
        '200':
          description: List of regions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRegionsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/databases/{database_id}/replicas:
    parameters:
      - $ref: '#/components/parameters/DatabaseId'
    get:
      operationId: listReplicas
      summary: List replicas
      description: Lists all read replicas for a database.
      tags:
        - Projects
      responses:
        '200':
          description: List of replicas.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListReplicasResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      operationId: createReplica
      summary: Add a replica
      description: Adds a read replica to a database.
      tags:
        - Projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReplicaRequest'
      responses:
        '201':
          description: Replica created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Replica'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/databases/{database_id}/replicas/{replica_id}:
    parameters:
      - $ref: '#/components/parameters/DatabaseId'
      - $ref: '#/components/parameters/ReplicaId'
    delete:
      operationId: deleteReplica
      summary: Delete a replica
      description: Removes a read replica from a database.
      tags:
        - Projects
      responses:
        '204':
          description: Replica deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/schema-annotations:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: listSchemaAnnotations
      summary: List schema annotations
      description: >
        Lists the project's human-written table and column descriptions. These are surfaced to connected agents through
        the MCP schema catalog.
      tags:
        - SchemaAnnotations
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: List of schema annotations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSchemaAnnotationsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    put:
      operationId: putSchemaAnnotation
      summary: Create or replace a schema annotation
      description: >
        Attaches an operator-written description to a table (omit column_name) or a column. Keyed by (schema_name,
        table_name, column_name); an existing annotation with the same key is replaced.
      tags:
        - SchemaAnnotations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SchemaAnnotationInput'
      responses:
        '200':
          description: The created or updated annotation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaAnnotation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      operationId: deleteSchemaAnnotation
      summary: Delete a schema annotation
      description: >
        Removes a single annotation identified by its natural key. Omit column_name to delete a table-level annotation,
        and omit schema_name to match the unqualified form.
      tags:
        - SchemaAnnotations
      parameters:
        - name: table_name
          in: query
          required: true
          description: Relation (table or view) the annotation describes.
          schema:
            type: string
            minLength: 1
            maxLength: 255
        - name: schema_name
          in: query
          required: false
          description: Optional schema. Omit to match the unqualified form.
          schema:
            type: string
            maxLength: 255
        - name: column_name
          in: query
          required: false
          description: Optional column. Omit to delete a table-level annotation.
          schema:
            type: string
            maxLength: 255
      responses:
        '204':
          description: Annotation deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/organizations/{org_id}/self-host-enrollments:
    parameters:
      - $ref: '#/components/parameters/OrgId'
    post:
      operationId: createSelfHostEnrollment
      summary: Issue a self-host enrollment token
      description: >-
        Issues an enrollment token a self-hosted (BYOC) proxy uses to authenticate to the control plane's config/audit
        gRPC stream. The token is returned once and cannot be retrieved again. Requires the Scale or enterprise plan.
      tags:
        - Platform
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSelfHostEnrollmentRequest'
      responses:
        '201':
          description: Enrollment created. Token shown once.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SelfHostEnrollmentSecret'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The organization's plan is not entitled to self-host.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    get:
      operationId: listSelfHostEnrollments
      summary: List self-host enrollments
      description: Lists an organization's self-host enrollments. Tokens are never returned.
      tags:
        - Platform
      responses:
        '200':
          description: List of enrollments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSelfHostEnrollmentsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v1/organizations/{org_id}/self-host-enrollments/{enrollment_id}:
    parameters:
      - $ref: '#/components/parameters/OrgId'
      - name: enrollment_id
        in: path
        required: true
        description: Unique enrollment identifier.
        schema:
          type: string
          pattern: ^[a-zA-Z0-9_.-]+$
          example: she_01h455vb4pex5vsknk084sn02q
    delete:
      operationId: revokeSelfHostEnrollment
      summary: Revoke a self-host enrollment
      description: >-
        Revokes an enrollment so its token can no longer authenticate a proxy. Connected proxies keep their last-known
        config until they reconnect.
      tags:
        - Platform
      responses:
        '204':
          description: Enrollment revoked.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/organizations/{org_id}/self-host-enrollments/{enrollment_id}/rotate:
    parameters:
      - $ref: '#/components/parameters/OrgId'
      - name: enrollment_id
        in: path
        required: true
        description: Unique enrollment identifier.
        schema:
          type: string
          pattern: ^[a-zA-Z0-9_.-]+$
          example: she_01h455vb4pex5vsknk084sn02q
    post:
      operationId: rotateSelfHostEnrollment
      summary: Rotate a self-host enrollment token
      description: >-
        Mints a new enrollment token in place, keeping the same enrollment id, metadata, and expiry. The swap is atomic:
        the old token stops authenticating new proxy connections the moment this call returns. An already-connected
        proxy keeps its existing gRPC streams until it disconnects, then must present the new token to reconnect. The
        new token is returned once and cannot be retrieved again.
      tags:
        - Platform
      responses:
        '200':
          description: Token rotated. New token shown once.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SelfHostEnrollmentSecret'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The enrollment is revoked and cannot be rotated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/organizations/{org_id}/support/cases:
    parameters:
      - $ref: '#/components/parameters/OrgId'
    get:
      operationId: listSupportCases
      summary: List support cases
      description: Lists support cases for the organization with optional status and search filters.
      tags:
        - Support
      parameters:
        - name: status
          in: query
          required: false
          description: Filter by case status.
          schema:
            $ref: '#/components/schemas/SupportCaseStatus'
        - name: search
          in: query
          required: false
          description: Search cases by title.
          schema:
            type: string
        - name: page_size
          in: query
          required: false
          description: Number of results per page (1-100, default 20).
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: page
          in: query
          required: false
          description: Page number (1-based, default 1).
          schema:
            type: integer
            minimum: 1
            default: 1
      responses:
        '200':
          description: List of support cases.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSupportCasesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: createSupportCase
      summary: Create a support case
      description: Creates a new support case with an initial message.
      tags:
        - Support
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSupportCaseRequest'
      responses:
        '201':
          description: Support case created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupportCase'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v1/organizations/{org_id}/support/cases/{case_id}:
    parameters:
      - $ref: '#/components/parameters/OrgId'
      - $ref: '#/components/parameters/SupportCaseId'
    get:
      operationId: getSupportCase
      summary: Get a support case
      description: Returns a support case with all its messages.
      tags:
        - Support
      responses:
        '200':
          description: Support case with messages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSupportCaseResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateSupportCase
      summary: Update a support case
      description: Updates the status of a support case (close or reopen).
      tags:
        - Support
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSupportCaseRequest'
      responses:
        '200':
          description: Updated support case.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupportCase'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/organizations/{org_id}/support/cases/{case_id}/messages:
    parameters:
      - $ref: '#/components/parameters/OrgId'
      - $ref: '#/components/parameters/SupportCaseId'
    post:
      operationId: createSupportMessage
      summary: Add a message to a support case
      description: Adds a new message to an existing support case thread.
      tags:
        - Support
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSupportMessageRequest'
      responses:
        '201':
          description: Message created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupportMessage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/internal/support/slack-event:
    post:
      operationId: handleSlackSupportEvent
      summary: Handle a Slack support event
      description: Receives a forwarded Slack event from the dashboard webhook handler and creates a support message.
      tags:
        - Internal
      security:
        - InternalSecret: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SlackEventPayload'
      responses:
        '200':
          description: Event processed.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/organizations/{org_id}/usage:
    get:
      operationId: getOrganizationUsage
      summary: Get organization usage
      description: Returns daily usage data aggregated across all projects in the organization.
      tags:
        - Analytics
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - name: start_date
          in: query
          required: true
          schema:
            type: string
            format: date
            example: '2024-01-01'
          description: Start date (inclusive, YYYY-MM-DD).
        - name: end_date
          in: query
          required: true
          schema:
            type: string
            format: date
            example: '2024-01-31'
          description: End date (inclusive, YYYY-MM-DD).
      responses:
        '200':
          description: Daily usage data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/usage:
    get:
      operationId: getProjectUsage
      summary: Get project usage
      description: Returns daily usage data for a specific project, broken down by region.
      tags:
        - Analytics
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: start_date
          in: query
          required: true
          schema:
            type: string
            format: date
            example: '2024-01-01'
          description: Start date (inclusive, YYYY-MM-DD).
        - name: end_date
          in: query
          required: true
          schema:
            type: string
            format: date
            example: '2024-01-31'
          description: End date (inclusive, YYYY-MM-DD).
      responses:
        '200':
          description: Daily usage data by region.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectUsageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/webhooks:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: createWebhookEndpoint
      x-feature-flag: agent-gateway
      summary: Create a webhook endpoint
      description: Creates a webhook endpoint that receives project event deliveries.
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointInput'
      responses:
        '201':
          description: Webhook endpoint created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    get:
      operationId: listWebhookEndpoints
      x-feature-flag: agent-gateway
      summary: List webhook endpoints
      description: Lists webhook endpoints for the project.
      tags:
        - Webhooks
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: List of webhook endpoints.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWebhookEndpointsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/projects/{project_id}/webhooks/{webhook_id}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/WebhookId'
    get:
      operationId: getWebhookEndpoint
      x-feature-flag: agent-gateway
      summary: Get a webhook endpoint
      description: Returns a single webhook endpoint by ID.
      tags:
        - Webhooks
      responses:
        '200':
          description: The webhook endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateWebhookEndpoint
      x-feature-flag: agent-gateway
      summary: Update a webhook endpoint
      description: Updates a webhook endpoint.
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointInput'
      responses:
        '200':
          description: Updated webhook endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteWebhookEndpoint
      x-feature-flag: agent-gateway
      summary: Delete a webhook endpoint
      description: Deletes a webhook endpoint and its pending deliveries.
      tags:
        - Webhooks
      responses:
        '204':
          description: Webhook endpoint deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/projects/{project_id}/webhooks/{webhook_id}/test:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/WebhookId'
    post:
      operationId: testWebhookEndpoint
      x-feature-flag: agent-gateway
      summary: Send a test event
      description: Enqueues a test event delivery to the webhook endpoint.
      tags:
        - Webhooks
      responses:
        '202':
          description: Test delivery enqueued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookTestResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    OrgId:
      name: org_id
      in: path
      required: true
      description: Unique organization identifier.
      schema:
        type: string
        pattern: ^[a-zA-Z0-9_.-]+$
        example: org_abc123
    ProjectId:
      name: project_id
      in: path
      required: true
      description: Unique project identifier (prefixed, e.g. prj_xxx).
      schema:
        type: string
        pattern: ^[a-zA-Z0-9_.-]+$
    DatabaseId:
      name: database_id
      in: path
      required: true
      description: Unique database identifier (prefixed, e.g. db_xxx).
      schema:
        type: string
        pattern: ^[a-zA-Z0-9_.-]+$
    DomainId:
      name: domain_id
      in: path
      required: true
      description: Unique custom domain identifier (prefixed, e.g. dom_xxx).
      schema:
        type: string
        pattern: ^[a-zA-Z0-9_.-]+$
    ReplicaId:
      name: replica_id
      in: path
      required: true
      description: Unique replica identifier (prefixed, e.g. rep_xxx).
      schema:
        type: string
        pattern: ^[a-zA-Z0-9_.-]+$
    SupportCaseId:
      name: case_id
      in: path
      required: true
      description: Unique support case identifier (prefixed, e.g. sc_xxx).
      schema:
        type: string
        pattern: ^[a-zA-Z0-9_.-]+$
    PolicyId:
      name: policy_id
      in: path
      required: true
      description: Unique policy profile identifier (prefixed, e.g. pol_xxx).
      schema:
        type: string
        pattern: ^[a-zA-Z0-9_.-]+$
    AgentId:
      name: agent_id
      in: path
      required: true
      description: Unique agent credential identifier (prefixed, e.g. agt_xxx).
      schema:
        type: string
        pattern: ^[a-zA-Z0-9_.-]+$
    ApprovalId:
      name: approval_id
      in: path
      required: true
      description: Unique approval request identifier (prefixed, e.g. apr_xxx).
      schema:
        type: string
        pattern: ^[a-zA-Z0-9_.-]+$
    WebhookId:
      name: webhook_id
      in: path
      required: true
      description: Unique webhook endpoint identifier (prefixed, e.g. whk_xxx).
      schema:
        type: string
        pattern: ^[a-zA-Z0-9_.-]+$
    HoneytokenId:
      name: honeytoken_id
      in: path
      required: true
      description: Unique honeytoken identifier (prefixed, e.g. hnt_xxx).
      schema:
        type: string
        pattern: ^[a-zA-Z0-9_.-]+$
    AnomalyId:
      name: anomaly_id
      in: path
      required: true
      description: Unique anomaly alert identifier (prefixed, e.g. ano_xxx).
      schema:
        type: string
        pattern: ^[a-zA-Z0-9_.-]+$
    BranchId:
      name: branch_id
      in: path
      required: true
      description: Unique sandbox branch identifier (prefixed, e.g. brn_xxx).
      schema:
        type: string
        pattern: ^[a-zA-Z0-9_.-]+$
    PageSize:
      name: page_size
      in: query
      required: false
      description: Maximum number of items to return (1-100, default 20).
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    PageToken:
      name: page_token
      in: query
      required: false
      description: Opaque token for cursor-based pagination.
      schema:
        type: string
        pattern: ^[a-zA-Z0-9_.-]+$
    AuditCredentialId:
      name: credential_id
      in: query
      required: false
      description: Filter to a single agent credential.
      schema:
        type: string
        pattern: ^[a-zA-Z0-9_.-]+$
    AuditEvent:
      name: event
      in: query
      required: false
      description: Filter to a single event type (e.g. blocked, masked, query).
      schema:
        type: string
        pattern: ^[a-z_]+$
    AuditDecision:
      name: decision
      in: query
      required: false
      description: >-
        Coarse outcome filter that groups events. `allow` = query; `block` = blocked, budget_exhausted, auth_failed,
        credential_expired; `mask` = masked; `truncate` = truncated.
      schema:
        $ref: '#/components/schemas/AuditDecision'
    AuditSource:
      name: source
      in: query
      required: false
      description: Filter by statement origin (wire, mcp, rest, or control).
      schema:
        $ref: '#/components/schemas/AuditSource'
    AuditStart:
      name: start
      in: query
      required: false
      description: Return entries at or after this timestamp (inclusive lower bound).
      schema:
        type: string
        format: date-time
    AuditEnd:
      name: end
      in: query
      required: false
      description: Return entries strictly older than this timestamp (cursor / upper bound).
      schema:
        type: string
        format: date-time
  responses:
    BadRequest:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid authentication.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Operation not allowed by current plan limits.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Resource already exists or conflicts with current state.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limited. Try again later.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
            example: 60
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT issued by Better Auth. Verified via JWKS.
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: APIKey
      description: 'API key issued via the dashboard. Pass it as `Authorization: Bearer <api-key>`.'
    InternalSecret:
      type: apiKey
      in: header
      name: X-Internal-Secret
      description: Shared secret for dashboard-to-API service calls.
  schemas:
    AccountExport:
      type: object
      description: Full account data export for privacy and data-portability requests.
      required:
        - user
        - organizations
        - projects
        - databases
        - sessions
        - email_preferences
        - consents
        - audit_logs
        - exported_at
      properties:
        user:
          type: object
          description: Core user profile data.
          required:
            - id
            - name
            - email
            - email_verified
            - created_at
            - updated_at
          properties:
            id:
              type: string
              description: User identifier.
            name:
              type: string
              description: Display name for the user.
            email:
              type: string
              format: email
              description: Primary account email address.
            email_verified:
              type: boolean
              description: Whether the email address has been verified.
            image:
              type: string
              description: Avatar image URL, if present.
            created_at:
              type: string
              format: date-time
              description: When the user account was created.
            updated_at:
              type: string
              format: date-time
              description: When the user profile was last updated.
        organizations:
          type: array
          description: Organizations the user belongs to.
          items:
            type: object
            required:
              - id
              - name
              - slug
              - role
              - created_at
            properties:
              id:
                type: string
                description: Organization identifier.
              name:
                type: string
                description: Organization display name.
              slug:
                type: string
                description: Organization slug used in URLs and routing.
              role:
                type: string
                description: User role within the organization.
              created_at:
                type: string
                format: date-time
                description: When the organization membership was created.
        projects:
          type: array
          description: Projects owned through the user's organizations.
          items:
            type: object
            required:
              - id
              - org_id
              - name
              - description
              - status
              - created_at
            properties:
              id:
                type: string
                description: Project identifier.
              org_id:
                type: string
                description: Owning organization identifier.
              name:
                type: string
                description: Project display name.
              description:
                type: string
                description: Project description at export time.
              status:
                type: string
                description: Project lifecycle status.
              created_at:
                type: string
                format: date-time
                description: When the project was created.
        databases:
          type: array
          description: Databases registered under the exported projects.
          items:
            type: object
            required:
              - id
              - project_id
              - host
              - port
              - name
              - ssl_mode
              - role
              - created_at
            properties:
              id:
                type: string
                description: Database identifier.
              project_id:
                type: string
                description: Owning project identifier.
              host:
                type: string
                description: Upstream PostgreSQL host.
              port:
                type: integer
                description: Upstream PostgreSQL port.
              name:
                type: string
                description: Upstream PostgreSQL database name.
              ssl_mode:
                type: string
                description: PostgreSQL SSL mode in use for the database.
              role:
                type: string
                description: Database role within the project.
              created_at:
                type: string
                format: date-time
                description: When the database registration was created.
        sessions:
          type: array
          description: Auth sessions associated with the user.
          items:
            type: object
            required:
              - id
              - expires_at
              - created_at
            properties:
              id:
                type: string
                description: Session identifier.
              expires_at:
                type: string
                format: date-time
                description: When the session expires.
              created_at:
                type: string
                format: date-time
                description: When the session was created.
              ip_address:
                type: string
                description: IP address used to create the session, if known.
              user_agent:
                type: string
                description: User agent captured for the session, if known.
        email_preferences:
          type: object
          description: User communication preferences.
          properties:
            marketing_emails:
              type: boolean
              description: Whether marketing emails are enabled.
            usage_limit_alerts:
              type: boolean
              description: Whether usage alert emails are enabled.
        consents:
          type: array
          description: Recorded legal-document acceptances for the user.
          items:
            type: object
            required:
              - id
              - document_type
              - document_version
              - accepted_at
            properties:
              id:
                type: string
                description: Consent record identifier.
              document_type:
                type: string
                description: Legal document type accepted by the user.
              document_version:
                type: string
                description: Accepted document version.
              accepted_at:
                type: string
                format: date-time
                description: When the document was accepted.
              ip_address:
                type: string
                description: IP address captured when consent was recorded.
        audit_logs:
          type: array
          description: Recent audit log entries associated with the account.
          items:
            type: object
            required:
              - id
              - action
              - created_at
            properties:
              id:
                type: string
                description: Audit log entry identifier.
              action:
                type: string
                description: Action captured by the audit log entry.
              resource_type:
                type: string
                description: Type of resource affected by the action.
              resource_id:
                type: string
                description: Identifier of the affected resource.
              ip_address:
                type: string
                description: IP address associated with the action, if known.
              created_at:
                type: string
                format: date-time
                description: When the audit log entry was recorded.
        exported_at:
          type: string
          format: date-time
          description: When the export was generated.
    AgentCredential:
      type: object
      description: A PgBeam-issued, scoped Postgres login plus hosted MCP token for an AI agent.
      required:
        - id
        - project_id
        - policy_profile_id
        - name
        - pg_username
        - status
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: Unique agent credential identifier (prefixed).
          example: agt_01h455vb4pex5vsknk084sn02q
        project_id:
          type: string
          description: Owning project ID.
          example: prj_01h455vb4pex5vsknk084sn02q
        policy_profile_id:
          type: string
          description: Policy profile enforced for this credential.
          example: pol_01h455vb4pex5vsknk084sn02q
        name:
          type: string
          description: Human-readable label for the credential.
          example: Claude Code (analytics)
        pg_username:
          type: string
          description: The Postgres username this credential presents to the proxy.
          example: agent_a1b2c3d4e5f6
        status:
          type: string
          description: Lifecycle status of the credential.
          enum:
            - active
            - disabled
            - revoked
        principal_type:
          type: string
          enum:
            - agent
            - human
          default: agent
          description: Whether this credential represents an autonomous agent or a human operator.
        auth_method:
          type: string
          enum:
            - cleartext
            - scram-sha-256
          default: scram-sha-256
          readOnly: true
          description: Postgres auth method the proxy presents for this credential.
        last_used_at:
          type: string
          format: date-time
          nullable: true
          description: When the credential was last used to connect, if ever.
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            When the credential expires and becomes unusable. Null means it never expires. Enforcement is fail-closed in
            the proxy the instant this time passes, before any cleanup sweep runs.
        created_at:
          type: string
          format: date-time
          description: When the credential was created.
        updated_at:
          type: string
          format: date-time
          description: When the credential was last updated.
    CreateAgentCredentialRequest:
      type: object
      description: Request body for issuing a new agent credential.
      required:
        - name
        - policy_profile_id
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 128
          description: Human-readable label for the credential.
        policy_profile_id:
          type: string
          description: The policy profile to enforce for this credential.
        principal_type:
          type: string
          enum:
            - agent
            - human
          default: agent
          description: Whether this credential represents an autonomous agent or a human operator.
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            Optional expiry. When set, the credential becomes unusable at this time (must be in the future). Omit or set
            null for a credential that never expires.
    AgentCredentialSecrets:
      type: object
      description: One-time secrets returned only at creation. The connection string and MCP token are not retrievable again.
      required:
        - credential
        - connection_string
        - mcp_url
        - mcp_token
      properties:
        credential:
          $ref: '#/components/schemas/AgentCredential'
        connection_string:
          type: string
          description: Guarded Postgres connection string for this agent credential.
          example: postgresql://agent_a1b2c3d4e5f6:secret@abc.proxy.pgbeam.app:5432/mydb
        mcp_url:
          type: string
          description: >-
            Hosted agent-database MCP endpoint for this project, served by the edge proxy on the same per-project host
            the agent connects to over the wire. Paste into an MCP client (Claude Code, Cursor, …) with the mcp_token as
            a bearer token.
          example: https://abc.proxy.pgbeam.app/mcp
        mcp_token:
          type: string
          description: Bearer token for the hosted MCP endpoint (shown once).
          example: pba_a1b2c3d4e5f6g7h8
    UpdateAgentCredentialStatusRequest:
      type: object
      description: Request body for enabling or disabling an agent credential.
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - active
            - disabled
          description: Set active to re-enable or disabled to kill-switch. Use DELETE to revoke permanently.
    ListAgentCredentialsResponse:
      type: object
      description: Cursor-paginated list of agent credentials for a project.
      required:
        - agents
      properties:
        agents:
          type: array
          description: Agent credentials on the current page.
          items:
            $ref: '#/components/schemas/AgentCredential'
        next_page_token:
          type: string
          description: Token for the next page. Empty if no more results.
    AnomalyAlert:
      type: object
      description: A surfaced anomalous-behavior alert for review.
      required:
        - id
        - project_id
        - kind
        - severity
        - title
        - status
        - created_at
      properties:
        id:
          type: string
          description: Unique anomaly alert identifier (prefixed).
          example: ano_01h455vb4pex5vsknk084sn02q
        project_id:
          type: string
          description: Owning project ID.
        credential_id:
          type: string
          nullable: true
          description: Agent credential implicated, if any.
        kind:
          type: string
          description: Machine-readable anomaly kind (e.g. egress_spike, novel_query_shape).
        severity:
          type: string
          enum:
            - info
            - warning
            - critical
          description: Alert severity.
        title:
          type: string
          description: Human-readable summary.
        details:
          type: object
          additionalProperties: true
          description: Structured details about the anomaly.
        status:
          type: string
          enum:
            - open
            - acknowledged
            - resolved
          description: Triage state of the alert.
        window_start:
          type: string
          format: date-time
          nullable: true
          description: Start of the observation window, if applicable.
        window_end:
          type: string
          format: date-time
          nullable: true
          description: End of the observation window, if applicable.
        created_at:
          type: string
          format: date-time
          description: When the alert was raised.
        acknowledged_at:
          type: string
          format: date-time
          nullable: true
          description: When the alert was acknowledged, if any.
        acknowledged_by:
          type: string
          nullable: true
          description: User who acknowledged the alert, if any.
    UpdateAnomalyAlertRequest:
      type: object
      description: Request body for triaging an anomaly alert.
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - acknowledged
            - resolved
          description: New triage state for the alert.
    ListAnomalyAlertsResponse:
      type: object
      description: Cursor-paginated list of anomaly alerts for a project.
      required:
        - anomalies
      properties:
        anomalies:
          type: array
          description: Anomaly alerts on the current page.
          items:
            $ref: '#/components/schemas/AnomalyAlert'
        next_page_token:
          type: string
          description: Token for the next page. Empty if no more results.
    ApprovalRequest:
      type: object
      description: A statement held by the gateway awaiting a human approval decision.
      required:
        - id
        - project_id
        - policy_profile_id
        - sql
        - status
        - requested_at
        - expires_at
      properties:
        id:
          type: string
          description: Unique approval request identifier (prefixed).
          example: apr_01h455vb4pex5vsknk084sn02q
        project_id:
          type: string
          description: Owning project ID.
        credential_id:
          type: string
          nullable: true
          description: Agent credential that submitted the statement, if known.
        policy_profile_id:
          type: string
          description: Policy profile that required approval.
        region:
          type: string
          description: Data plane region that held the statement.
        session_id:
          type: string
          description: Identifier grouping a connection's statements.
        sql:
          type: string
          description: The held statement text.
        normalized_sql:
          type: string
          description: Statement with literals replaced by placeholders.
        statement_kind:
          type: string
          description: Parsed statement kind (e.g. update, delete, ddl).
        estimated_rows:
          type: integer
          format: int64
          nullable: true
          description: >-
            Best-effort estimate of how many rows the statement would affect, attached by the data plane when the
            statement was held. Either the planner estimate from EXPLAIN or the exact count observed in a rolled-back
            trial execution. Null when no estimate could be made; treat it as an estimate, not a guarantee.
        target_tables:
          type: array
          description: Relations the statement touches, from the gateway's parse analysis.
          items:
            type: string
        status:
          type: string
          enum:
            - pending
            - approved
            - rejected
            - expired
            - executed
            - failed
          description: Current state of the approval request.
        reason:
          type: string
          description: Human-readable note attached to a decision.
        requested_at:
          type: string
          format: date-time
          description: When the statement was first held.
        decided_at:
          type: string
          format: date-time
          nullable: true
          description: When a decision was recorded, if any.
        decided_by:
          type: string
          nullable: true
          description: User who decided, if any.
        expires_at:
          type: string
          format: date-time
          description: When the request expires if undecided.
    ApprovalDecisionRequest:
      type: object
      description: Optional note attached to an approve/reject decision.
      properties:
        reason:
          type: string
          maxLength: 500
          description: Human-readable note explaining the decision.
    ListApprovalRequestsResponse:
      type: object
      description: Cursor-paginated list of approval requests for a project.
      required:
        - approvals
      properties:
        approvals:
          type: array
          description: Approval requests on the current page.
          items:
            $ref: '#/components/schemas/ApprovalRequest'
        next_page_token:
          type: string
          description: Token for the next page. Empty if no more results.
    AuditDecision:
      type: string
      description: >-
        Coarse outcome filter that groups audit events. `allow` = query; `block` = blocked, budget_exhausted,
        auth_failed, credential_expired; `mask` = masked; `truncate` = truncated.
      enum:
        - allow
        - block
        - mask
        - truncate
    AuditSource:
      type: string
      description: Statement origin (wire, mcp, rest, or control).
      enum:
        - wire
        - mcp
        - rest
        - control
    AuditLogEntry:
      type: object
      description: One agent statement recorded by the gateway.
      required:
        - id
        - project_id
        - event
        - ts
      properties:
        id:
          type: string
          description: Unique audit entry identifier.
          example: aud_01h455vb4pex5vsknk084sn02q
        project_id:
          type: string
          description: Owning project ID.
        credential_id:
          type: string
          nullable: true
          description: Agent credential that issued the statement, if known.
        region:
          type: string
          description: Data plane region that served the statement.
        event:
          type: string
          description: Event type (query, blocked, masked, budget_exhausted, truncated, auth_failed, credential_expired).
        sql:
          type: string
          description: The statement text (truncated).
        normalized_sql:
          type: string
          description: Statement with literals replaced by placeholders.
        query_hash:
          type: string
          description: Hash of the normalized statement.
        statement_kind:
          type: string
          description: Parsed statement kind.
        decision_rule:
          type: string
          description: Machine-readable rule that produced a block, if any.
        reason:
          type: string
          description: Human-readable explanation of the decision.
        rows_returned:
          type: integer
          format: int64
          description: Rows returned to the agent.
        bytes_out:
          type: integer
          format: int64
          description: Bytes sent to the agent.
        latency_ms:
          type: number
          description: Statement latency in milliseconds.
        cache_status:
          type: string
          description: Cache outcome for the statement.
        client_ip:
          type: string
          description: Source IP of the agent connection.
        session_id:
          type: string
          description: Identifier grouping a connection's statements.
        source:
          type: string
          description: Statement origin (wire, mcp, rest, or control for control-plane lifecycle events).
        ts:
          type: string
          format: date-time
          description: When the statement executed.
        seq:
          type: integer
          format: int64
          description: Monotonic per-project position in the tamper-evident hash chain.
        prev_hash:
          type: string
          description: >-
            Hex SHA-256 of the previous chained entry (a fixed genesis value for the first entry). Empty for pre-chain
            legacy entries.
        entry_hash:
          type: string
          description: Hex SHA-256 of this entry's canonical content chained onto prev_hash. Empty for pre-chain legacy entries.
    ListAuditLogsResponse:
      type: object
      description: Time-ordered page of audit entries (newest first).
      required:
        - entries
      properties:
        entries:
          type: array
          description: Audit entries on the current page.
          items:
            $ref: '#/components/schemas/AuditLogEntry'
        next_page_token:
          type: string
          description: Cursor for the next page. Empty if no more results.
    AuditChainVerification:
      type: object
      description: >-
        Result of recomputing the project's tamper-evident audit hash chain over a time range. The chain links each
        entry to its predecessor, so editing or deleting any row breaks it.
      required:
        - ok
        - verified_count
        - unchained_count
        - verified_at
      properties:
        ok:
          type: boolean
          description: True when every chained entry in the range links correctly and no tampering or deletion was detected.
        verified_count:
          type: integer
          format: int64
          description: Number of chained entries checked.
        unchained_count:
          type: integer
          format: int64
          description: >-
            Pre-chain (legacy) entries in the range that predate the hash chain and were skipped rather than treated as
            tampering.
        chain_start_seq:
          type: integer
          format: int64
          nullable: true
          description: Sequence number of the first chained entry checked. Null when none.
        chain_end_seq:
          type: integer
          format: int64
          nullable: true
          description: Sequence number of the last chained entry checked. Null when none.
        first_broken_seq:
          type: integer
          format: int64
          nullable: true
          description: Sequence number where verification first failed (a tampered or deleted entry). Null when ok.
        failure_reason:
          type: string
          nullable: true
          description: >-
            Machine-readable failure kind: hash_mismatch (entry content edited), broken_link (prev_hash does not match
            the predecessor), or missing_entry (a sequence number was deleted). Null when ok.
        verified_at:
          type: string
          format: date-time
          description: When verification ran.
    OrganizationPlan:
      type: object
      description: Billing state and plan limits for an organization.
      required:
        - org_id
        - plan
        - limits
      properties:
        org_id:
          type: string
          description: Organization identifier the plan applies to.
          example: org_abc123
        plan:
          type: string
          enum:
            - starter
            - pro
            - scale
            - enterprise
          description: Current plan tier.
        billing_provider:
          type: string
          enum:
            - stripe
            - vercel
            - aws
            - manual
          description: Which billing provider manages this organization's subscription.
        subscription_status:
          type: string
          enum:
            - none
            - active
            - trialing
            - past_due
            - canceled
            - unpaid
            - incomplete
            - incomplete_expired
            - paused
          description: Stripe subscription status.
        current_period_end:
          type: string
          format: date-time
          description: End of current billing period.
        enabled:
          type: boolean
          description: Whether the organization billing is active (false = suspended).
        custom_pricing:
          type: boolean
          description: Whether the organization has custom enterprise pricing.
        spend_limit:
          type: number
          format: double
          nullable: true
          description: Monthly spend limit in dollars. Null means no limit.
          example: 500
        spend_capped:
          type: boolean
          description: >-
            Whether the organization has hit its spend limit and agent access is paused at the proxy. Lifts
            automatically when usage resets for the new billing period, or immediately when the spend limit is raised or
            removed.
        spend_capped_at:
          type: string
          format: date-time
          nullable: true
          description: When the spend cap was applied. Null when not capped.
        limits:
          $ref: '#/components/schemas/PlanLimits'
        created_at:
          type: string
          format: date-time
          description: When the billing record was created.
        updated_at:
          type: string
          format: date-time
          description: When the billing record was last updated.
    PlanLimits:
      type: object
      description: Effective usage limits enforced for an organization plan.
      required:
        - queries_per_day
        - max_projects
        - max_databases
        - max_connections
        - queries_per_second
        - bytes_per_month
        - max_query_shapes
        - included_seats
        - max_agent_credentials
        - audit_retention_days
        - sandbox_max_branches
        - sandbox_max_upstream_bytes
        - sandbox_idle_seconds
        - sandbox_ttl_seconds
      properties:
        queries_per_day:
          type: integer
          format: int64
          description: Maximum queries per day across all projects. 0 means unlimited.
        max_projects:
          type: integer
          description: Maximum number of active projects.
        max_databases:
          type: integer
          description: Maximum databases per project.
        max_connections:
          type: integer
          description: Maximum concurrent connections per project.
        queries_per_second:
          type: integer
          description: Maximum queries per second per project.
        bytes_per_month:
          type: integer
          format: int64
          description: Monthly data transfer quota in bytes. 0 means unlimited.
        max_query_shapes:
          type: integer
          description: Maximum query shapes in cache rules. 0 means unlimited.
        included_seats:
          type: integer
          description: Number of seats included in the plan.
        max_agent_credentials:
          type: integer
          description: Maximum agent credentials per organization. 0 means unlimited.
        audit_retention_days:
          type: integer
          description: Agent audit-log retention window in days.
        sandbox_max_branches:
          type: integer
          description: Maximum concurrently active instant (sandbox) branches. 0 means no limit.
        sandbox_max_upstream_bytes:
          type: integer
          format: int64
          description: Maximum upstream source-database size a sandbox base sync accepts, in bytes. 0 means no limit.
        sandbox_idle_seconds:
          type: integer
          description: Idle time before an instant (sandbox) branch scales to zero, in seconds.
        sandbox_ttl_seconds:
          type: integer
          description: Lifetime of an instant (sandbox) branch before the TTL sweep discards it, in seconds.
    PlanInfo:
      type: object
      description: Publicly visible plan metadata and limits.
      required:
        - name
        - label
        - monthly_price
        - limits
      properties:
        name:
          type: string
          description: Plan tier name (starter, pro, scale).
        label:
          type: string
          description: Display label for the plan.
        monthly_price:
          type: integer
          description: Monthly price in dollars.
        annual_price:
          type: integer
          description: Annual price in dollars (if applicable).
        description:
          type: string
          description: Short description of the plan.
        overage_text:
          type: string
          description: Human-readable overage pricing text.
        trial_days:
          type: integer
          description: Number of trial days for new signups.
        limits:
          $ref: '#/components/schemas/PlanLimits'
    ListPlansResponse:
      type: object
      description: Response envelope for listing available billing plans.
      required:
        - plans
      properties:
        plans:
          type: array
          description: Billing plans available for self-serve signups.
          items:
            $ref: '#/components/schemas/PlanInfo'
    UpdateSpendLimitRequest:
      type: object
      description: Request body for updating an organization's monthly spend cap.
      properties:
        spend_limit:
          type: number
          format: double
          nullable: true
          description: Monthly spend limit in dollars. Null to remove the limit.
          example: 500
    CancellationFeedbackRequest:
      type: object
      description: Request body for capturing cancellation feedback from a user.
      properties:
        reason:
          type: string
          description: Predefined cancellation reason.
          example: too-expensive
        feedback:
          type: string
          description: Free-text feedback from the user.
          example: Switching to a self-hosted solution.
    VercelResourceStatus:
      type: object
      description: A PgBeam project provisioned as a Vercel Marketplace resource, with current-period usage.
      required:
        - resource_id
        - project_id
        - name
        - billing_plan_id
        - status
        - period_queries
        - period_bytes
      properties:
        resource_id:
          type: string
          description: Vercel resource identifier.
        project_id:
          type: string
          description: PgBeam project identifier backing the resource.
        name:
          type: string
          description: Human-readable resource/project name.
        billing_plan_id:
          type: string
          description: Plan tier the resource is billed on.
        status:
          type: string
          enum:
            - ready
            - suspended
            - deleted
          description: Current resource lifecycle status.
        period_queries:
          type: integer
          format: int64
          description: Queries this resource has served in the current billing period.
        period_bytes:
          type: integer
          format: int64
          description: Bytes transferred by this resource in the current billing period.
    VercelInstallationStatus:
      type: object
      description: Vercel Marketplace installation status for an organization, including its resources.
      required:
        - installation_id
        - vercel_account_id
        - plan
        - status
        - resources
      properties:
        installation_id:
          type: string
          description: Vercel installation (integration configuration) identifier.
        vercel_account_id:
          type: string
          description: Vercel account/team identifier that owns the installation.
        plan:
          type: string
          description: Current plan tier for the organization.
        status:
          type: string
          description: Installation status (active).
        created_at:
          type: string
          format: date-time
          description: When the installation was created.
        resources:
          type: array
          description: Resources (projects) provisioned under this installation.
          items:
            $ref: '#/components/schemas/VercelResourceStatus'
    DatabaseBranch:
      type: object
      description: An ephemeral sandbox branch of a database used for write isolation.
      required:
        - id
        - database_id
        - branch_name
        - status
        - created_at
      properties:
        id:
          type: string
          description: Unique sandbox branch identifier (prefixed).
          example: brn_01h455vb4pex5vsknk084sn02q
        database_id:
          type: string
          description: Database this branch was created from.
        credential_id:
          type: string
          nullable: true
          description: Agent credential that requested the branch, if known.
        session_id:
          type: string
          description: Identifier grouping a connection's statements.
        branch_name:
          type: string
          description: Generated name for the branch.
        status:
          type: string
          enum:
            - pending
            - ready
            - error
            - discarded
          description: Provisioning state of the branch.
        error:
          type: string
          description: Provisioning error, if any.
        created_at:
          type: string
          format: date-time
          description: When the branch was created.
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: When the branch expires, if set.
        discarded_at:
          type: string
          format: date-time
          nullable: true
          description: When the branch was discarded, if any.
    ListDatabaseBranchesResponse:
      type: object
      description: Cursor-paginated list of sandbox branches for a project.
      required:
        - branches
      properties:
        branches:
          type: array
          description: Sandbox branches on the current page.
          items:
            $ref: '#/components/schemas/DatabaseBranch'
        next_page_token:
          type: string
          description: Token for the next page. Empty if no more results.
    CacheRuleEntry:
      type: object
      description: Observed query shape and its cache recommendation for a database.
      required:
        - query_hash
        - normalized_sql
        - query_type
        - cache_enabled
        - call_count
        - avg_latency_ms
        - p95_latency_ms
        - avg_response_bytes
        - stability_rate
        - recommendation
        - first_seen_at
        - last_seen_at
      properties:
        query_hash:
          type: string
          description: xxhash64 hex of the normalized SQL.
          example: a1b2c3d4e5f60718
        normalized_sql:
          type: string
          description: SQL with literals replaced by $N placeholders.
          example: SELECT * FROM users WHERE id = $1
        query_type:
          type: string
          enum:
            - read
            - write
            - other
          description: Query classification.
        cache_enabled:
          type: boolean
          description: Whether caching is enabled for this query shape.
        cache_ttl_seconds:
          type: integer
          nullable: true
          minimum: 0
          description: TTL override in seconds. Null means use project default.
          example: 300
        cache_swr_seconds:
          type: integer
          nullable: true
          minimum: 0
          description: SWR override in seconds. Null means use project default.
          example: 60
        call_count:
          type: integer
          format: int64
          description: Total number of executions observed.
        avg_latency_ms:
          type: number
          format: double
          description: Average query latency in milliseconds.
        p95_latency_ms:
          type: number
          format: double
          description: 95th percentile latency in milliseconds.
        avg_response_bytes:
          type: integer
          format: int64
          description: Average response size in bytes.
        stability_rate:
          type: number
          format: double
          description: Response stability rate (0.0 to 1.0). Higher means more stable.
        recommendation:
          type: string
          enum:
            - great
            - good
            - fair
            - poor
          description: Cache recommendation based on frequency, latency, and stability.
        first_seen_at:
          type: string
          format: date-time
          description: When this query was first observed.
        last_seen_at:
          type: string
          format: date-time
          description: When this query was last observed.
    ListCacheRulesResponse:
      type: object
      description: Cursor-paginated cache-rule entries for a database.
      required:
        - entries
      properties:
        entries:
          type: array
          description: Query shapes returned for the current page.
          items:
            $ref: '#/components/schemas/CacheRuleEntry'
        next_page_token:
          type: string
          description: Opaque token for cursor-based pagination.
    UpdateCacheRuleRequest:
      type: object
      description: Request body for updating cache behavior of a query shape.
      required:
        - cache_enabled
      properties:
        cache_enabled:
          type: boolean
          description: Whether to enable caching for this query shape.
        cache_ttl_seconds:
          type: integer
          nullable: true
          minimum: 0
          maximum: 86400
          description: TTL override in seconds. Null to use project default.
          example: 300
        cache_swr_seconds:
          type: integer
          nullable: true
          minimum: 0
          maximum: 86400
          description: SWR override in seconds. Null to use project default.
          example: 60
    UpdateCacheRuleResponse:
      type: object
      description: Response returned after updating a cache rule.
      required:
        - entry
      properties:
        entry:
          $ref: '#/components/schemas/CacheRuleEntry'
    Error:
      type: object
      description: Standard error response envelope for PgBeam API requests.
      required:
        - error
      properties:
        error:
          type: object
          description: Error metadata for the failed request.
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Machine-readable error code.
            message:
              type: string
              description: Human-readable error message.
    Database:
      type: object
      description: Registered upstream PostgreSQL database for a project.
      required:
        - id
        - project_id
        - host
        - port
        - name
        - username
        - ssl_mode
        - cache_config
        - pool_config
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: Unique database identifier (prefixed).
          example: db_01h455vb4pex5vsknk084sn02q
        project_id:
          type: string
          description: Owning project ID.
          example: prj_01h455vb4pex5vsknk084sn02q
        connection_string:
          type: string
          description: Connection string for connecting through PgBeam proxy. Password is replaced with a placeholder.
          readOnly: true
          example: postgresql://myuser:YOUR_PASSWORD@myproject.proxy.pgbeam.app:5432/mydb
        host:
          type: string
          description: PostgreSQL host.
          example: db.example.com
        port:
          type: integer
          minimum: 1
          maximum: 65535
          description: PostgreSQL port.
          example: 5432
        name:
          type: string
          description: PostgreSQL database name.
          example: mydb
        username:
          type: string
          description: PostgreSQL username.
          example: pgbeam
        ssl_mode:
          $ref: '#/components/schemas/SSLMode'
        role:
          $ref: '#/components/schemas/DatabaseRole'
        pool_region:
          type: string
          description: >
            Region where the connection pool is maintained (near the database). When set and different from the client's
            edge region, queries are relayed through the pool region's data plane. Empty means direct connection.
          example: us-east-1
        query_timeout_ms:
          type: integer
          minimum: 0
          maximum: 300000
          default: 0
          description: >
            Query timeout in milliseconds. When set (> 0), the proxy sends SET statement_timeout on upstream
            connections. 0 means disabled (default).
        auto_read_routing:
          type: boolean
          default: false
          description: >
            When enabled and replicas are configured, SELECT queries automatically route to read replicas without
            requiring the @pgbeam:replica SQL annotation.
        cache_config:
          $ref: '#/components/schemas/CacheConfig'
        pool_config:
          $ref: '#/components/schemas/PoolConfig'
        created_at:
          type: string
          format: date-time
          description: When the database registration was created.
        updated_at:
          type: string
          format: date-time
          description: When the database registration was last updated.
    DatabaseRole:
      type: string
      enum:
        - primary
        - replica
      description: Database role. Primary receives writes, replicas receive reads.
      default: primary
    SSLMode:
      type: string
      enum:
        - disable
        - allow
        - prefer
        - require
        - verify-ca
        - verify-full
      description: PostgreSQL SSL connection mode.
      example: require
    CacheConfig:
      type: object
      description: Query cache configuration.
      required:
        - enabled
        - ttl_seconds
        - max_entries
        - swr_seconds
      properties:
        enabled:
          type: boolean
          default: true
          description: Whether query caching is enabled. When false, all queries bypass the cache.
        ttl_seconds:
          type: integer
          minimum: 0
          maximum: 86400
          default: 60
          description: Cache TTL in seconds for query results.
        max_entries:
          type: integer
          minimum: 0
          maximum: 1000000
          default: 10000
          description: Maximum number of cached query results.
        swr_seconds:
          type: integer
          minimum: 0
          maximum: 86400
          default: 30
          description: Stale-while-revalidate window in seconds.
    PoolConfig:
      type: object
      description: Connection pool configuration.
      required:
        - pool_size
        - min_pool_size
        - pool_mode
      properties:
        pool_size:
          type: integer
          minimum: 1
          maximum: 10000
          default: 10
          description: Maximum connections in the pool.
          example: 20
        min_pool_size:
          type: integer
          minimum: 1
          maximum: 10000
          default: 1
          description: Minimum idle connections maintained.
          example: 5
        pool_mode:
          $ref: '#/components/schemas/PoolMode'
        max_active:
          type: integer
          minimum: 1
          maximum: 10000
          default: 200
          description: Maximum concurrent upstream connections per pool.
    PoolMode:
      type: string
      enum:
        - session
        - transaction
        - statement
      description: Connection pool mode.
      example: transaction
    CreateDatabaseRequest:
      type: object
      description: Request body for registering an upstream database.
      required:
        - host
        - port
        - name
        - username
        - password
      properties:
        host:
          type: string
          minLength: 1
          pattern: ^[^\s\x00]+$
          description: PostgreSQL host.
          example: db.example.com
        port:
          type: integer
          minimum: 1
          maximum: 65535
          description: PostgreSQL port.
          example: 5432
        name:
          type: string
          minLength: 1
          pattern: ^[^\x00]+$
          description: PostgreSQL database name.
          example: mydb
        username:
          type: string
          minLength: 1
          pattern: ^[^\x00]+$
          description: PostgreSQL username.
          example: pgbeam
        password:
          type: string
          format: password
          minLength: 1
          pattern: ^[^\x00]+$
          description: PostgreSQL password. Stored encrypted at rest.
          writeOnly: true
        ssl_mode:
          $ref: '#/components/schemas/SSLMode'
        role:
          $ref: '#/components/schemas/DatabaseRole'
        pool_region:
          type: string
          description: >
            Region where the connection pool is maintained (near the database). When set and different from the client's
            edge region, queries are relayed through the pool region's data plane. Empty means direct connection.
          example: us-east-1
        query_timeout_ms:
          type: integer
          minimum: 0
          maximum: 300000
          default: 0
          description: |
            Query timeout in milliseconds. 0 means disabled (default).
        auto_read_routing:
          type: boolean
          default: false
          description: |
            Auto-route SELECT queries to read replicas.
        cache_config:
          $ref: '#/components/schemas/CacheConfig'
        pool_config:
          $ref: '#/components/schemas/PoolConfig'
    UpdateDatabaseRequest:
      type: object
      description: Request body for partially updating an upstream database.
      properties:
        host:
          type: string
          minLength: 1
          pattern: ^[^\x00]+$
          description: Updated PostgreSQL host.
          example: db.example.com
        port:
          type: integer
          minimum: 1
          maximum: 65535
          description: Updated PostgreSQL port.
          example: 5432
        name:
          type: string
          pattern: ^[^\x00]*$
          description: Updated PostgreSQL database name.
          example: mydb
        username:
          type: string
          pattern: ^[^\x00]*$
          description: Updated PostgreSQL username.
          example: pgbeam
        password:
          type: string
          format: password
          pattern: ^[^\x00]*$
          description: Updated PostgreSQL password.
          writeOnly: true
        ssl_mode:
          $ref: '#/components/schemas/SSLMode'
        role:
          $ref: '#/components/schemas/DatabaseRole'
        pool_region:
          type: string
          description: >
            Region where the connection pool is maintained (near the database). When set and different from the client's
            edge region, queries are relayed through the pool region's data plane. Empty means direct connection.
          example: us-east-1
        query_timeout_ms:
          type: integer
          minimum: 0
          maximum: 300000
          description: |
            Query timeout in milliseconds. 0 means disabled.
        auto_read_routing:
          type: boolean
          description: |
            Auto-route SELECT queries to read replicas.
        cache_config:
          $ref: '#/components/schemas/CacheConfig'
        pool_config:
          $ref: '#/components/schemas/PoolConfig'
    ListDatabasesResponse:
      type: object
      description: Cursor-paginated list of databases attached to a project.
      required:
        - databases
      properties:
        databases:
          type: array
          description: Databases on the current page.
          items:
            $ref: '#/components/schemas/Database'
        next_page_token:
          type: string
          description: Token for the next page. Empty if no more results.
    TestConnectionResult:
      type: object
      description: Result of testing connectivity to an upstream database.
      required:
        - ok
      properties:
        ok:
          type: boolean
          description: Whether the connection test succeeded.
        latency_ms:
          type: number
          nullable: true
          description: Round-trip connection time in milliseconds.
        error:
          type: string
          description: Error message if the connection test failed.
        server_version:
          type: string
          description: PostgreSQL server version string, if available.
    CustomDomain:
      type: object
      description: Custom database hostname attached to a project.
      required:
        - id
        - project_id
        - domain
        - verified
        - dns_verification_token
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: Unique domain identifier (prefixed).
          example: dom_01h455vb4pex5vsknk084sn02q
        project_id:
          type: string
          description: Owning project ID.
          example: prj_01h455vb4pex5vsknk084sn02q
        domain:
          type: string
          description: The custom domain name.
          example: db.example.com
        verified:
          type: boolean
          description: Whether DNS ownership has been verified.
        verified_at:
          type: string
          format: date-time
          nullable: true
          description: When DNS verification was completed.
        tls_cert_expiry:
          type: string
          format: date-time
          nullable: true
          description: When the TLS certificate expires.
        dns_verification_token:
          type: string
          description: Token value for the DNS TXT record verification.
        dns_instructions:
          $ref: '#/components/schemas/DnsInstructions'
        created_at:
          type: string
          format: date-time
          description: When the custom domain was created.
        updated_at:
          type: string
          format: date-time
          description: When the custom domain was last updated.
    CreateCustomDomainRequest:
      type: object
      description: Request body for attaching a custom domain to a project.
      required:
        - domain
      properties:
        domain:
          type: string
          minLength: 1
          maxLength: 253
          pattern: ^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*$
          description: The custom domain name to add (e.g., db.example.com).
          example: db.example.com
    ListCustomDomainsResponse:
      type: object
      description: Cursor-paginated list of custom domains for a project.
      required:
        - domains
      properties:
        domains:
          type: array
          description: Custom domains on the current page.
          items:
            $ref: '#/components/schemas/CustomDomain'
        next_page_token:
          type: string
          description: Token for the next page. Empty if no more results.
    DnsInstructions:
      type: object
      description: DNS records the user needs to create for domain verification.
      properties:
        cname_host:
          type: string
          description: The CNAME record host.
          example: db.example.com
        cname_target:
          type: string
          description: The CNAME record target.
          example: abc.proxy.pgbeam.app
        txt_host:
          type: string
          description: The TXT record host for verification.
          example: _pgbeam-verify.db.example.com
        txt_value:
          type: string
          description: The TXT record value for verification.
          example: pgbeam-verify=abc123token
        acme_cname_host:
          type: string
          description: The CNAME record host for ACME TLS certificate issuance.
          example: _acme-challenge.db.example.com
        acme_cname_target:
          type: string
          description: The CNAME target for ACME challenge delegation.
          example: _acme-challenge.abc.proxy.pgbeam.app
    VerifyCustomDomainResponse:
      type: object
      description: Result of checking DNS ownership for a custom domain.
      required:
        - verified
      properties:
        verified:
          type: boolean
          description: Whether DNS verification succeeded.
        error:
          type: string
          description: Error message if verification failed.
        domain:
          $ref: '#/components/schemas/CustomDomain'
    HealthResponse:
      type: object
      description: Health status and build metadata for the API service.
      required:
        - status
        - version
        - image_sha
      properties:
        status:
          type: string
          enum:
            - ok
            - degraded
          description: Overall service health.
        version:
          type: string
          description: API server version.
          example: 1.0.0
        image_sha:
          type: string
          description: Resolved image SHA (digest or SHA tag).
          example: f1f01eda9e1bc25a3a1d28b1e18c5579fa9a128fede12169d3a392504f9729e4
        timestamp:
          type: string
          format: date-time
          description: Server time.
    Honeytoken:
      type: object
      description: >
        A decoy (canary) relation. Any agent statement that references it is blocked (fail closed) and recorded as a
        canary_tripped audit event.
      required:
        - id
        - project_id
        - relation_name
        - action
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: Unique honeytoken identifier.
          example: hnt_01j9x8y7z6w5v4u3t2s1r0q9p8
        project_id:
          type: string
          description: Project the honeytoken belongs to.
          example: prj_01j9x8y7z6w5v4u3t2s1r0q9p8
        schema_name:
          type: string
          nullable: true
          description: |
            Optional schema. Null matches the unqualified/public form, mirroring the relation allowlist normalization.
          example: public
        relation_name:
          type: string
          description: Relation (table or view) name of the decoy.
          example: customer_ssns
        action:
          type: string
          enum:
            - audit_only
            - kill
          description: >
            Response when tripped. audit_only blocks the statement, records the event, and fires webhooks. kill
            additionally disables the tripping credential via the kill-switch.
        created_at:
          type: string
          format: date-time
          description: When the honeytoken was registered.
        updated_at:
          type: string
          format: date-time
          description: When the honeytoken was last updated.
    HoneytokenInput:
      type: object
      description: Request body for creating or updating a honeytoken.
      required:
        - relation_name
        - action
      properties:
        schema_name:
          type: string
          nullable: true
          maxLength: 255
          description: Optional schema. Null or empty matches the unqualified/public form.
          example: public
        relation_name:
          type: string
          minLength: 1
          maxLength: 255
          description: Relation (table or view) name of the decoy.
          example: customer_ssns
        action:
          type: string
          enum:
            - audit_only
            - kill
          description: Response when the honeytoken is tripped.
    ListHoneytokensResponse:
      type: object
      description: Cursor-paginated honeytokens for a project.
      required:
        - honeytokens
      properties:
        honeytokens:
          type: array
          description: Honeytokens returned for the current page.
          items:
            $ref: '#/components/schemas/Honeytoken'
        next_page_token:
          type: string
          description: Opaque token for cursor-based pagination.
    QueryInsight:
      type: object
      description: Aggregated analytics for a normalized SQL query shape.
      required:
        - query_hash
        - query_pattern
        - total_count
        - total_cache_hits
        - total_cache_misses
        - avg_latency_ms
        - p99_latency_ms
      properties:
        query_hash:
          type: string
          description: xxhash64 of the normalized SQL pattern (hex).
        query_pattern:
          type: string
          description: Normalized SQL pattern (truncated to 500 chars).
        total_count:
          type: integer
          format: int64
          description: Total number of executions in the time range.
        total_cache_hits:
          type: integer
          format: int64
          description: Total cache hits attributed to the query shape.
        total_cache_misses:
          type: integer
          format: int64
          description: Total cache misses attributed to the query shape.
        avg_latency_ms:
          type: number
          format: double
          description: Average query latency in milliseconds.
        p99_latency_ms:
          type: number
          format: double
          description: P99 query latency in milliseconds.
    CacheSummary:
      type: object
      description: Aggregate cache performance metrics for the selected time range.
      required:
        - total_hits
        - total_misses
        - hit_rate
      properties:
        total_hits:
          type: integer
          format: int64
          description: Total number of cache hits in the selected time range.
        total_misses:
          type: integer
          format: int64
          description: Total number of cache misses in the selected time range.
        hit_rate:
          type: number
          format: double
          description: Cache hit rate as a fraction (0.0 to 1.0).
    LatencySummary:
      type: object
      description: Aggregate latency metrics for the selected time range.
      required:
        - avg_ms
        - p99_ms
      properties:
        avg_ms:
          type: number
          format: double
          description: Average latency in milliseconds across all queries.
        p99_ms:
          type: number
          format: double
          description: P99 latency in milliseconds across all queries.
    ProjectInsights:
      type: object
      description: Query insights, cache performance, and latency for a project.
      required:
        - queries
        - cache
        - latency
      properties:
        queries:
          type: array
          description: Top query shapes observed for the project.
          items:
            $ref: '#/components/schemas/QueryInsight'
        cache:
          $ref: '#/components/schemas/CacheSummary'
        latency:
          $ref: '#/components/schemas/LatencySummary'
    McpRequest:
      description: JSON-RPC 2.0 request envelope for MCP over Streamable HTTP.
      type: object
      required:
        - jsonrpc
        - method
      properties:
        jsonrpc:
          type: string
          enum:
            - '2.0'
          description: JSON-RPC version. Must be "2.0".
          example: '2.0'
        id:
          type: string
          description: Request identifier. Omit for notifications.
          example: '1'
        method:
          type: string
          enum:
            - initialize
            - notifications/initialized
            - tools/list
            - tools/call
            - ping
          description: MCP method to invoke.
          example: initialize
        params:
          type: object
          description: Method-specific parameters.
    McpResponse:
      description: JSON-RPC 2.0 response envelope for MCP over Streamable HTTP.
      type: object
      required:
        - jsonrpc
        - id
      properties:
        jsonrpc:
          type: string
          enum:
            - '2.0'
          description: JSON-RPC version. Always "2.0".
        id:
          type: string
          nullable: true
          description: Mirrors the request id. Null for parse errors.
        result:
          type: object
          description: Method-specific result (present on success).
        error:
          type: object
          properties:
            code:
              type: integer
              description: JSON-RPC error code.
            message:
              type: string
              description: Human-readable error message.
          description: JSON-RPC error (present on failure).
    MigrationLintRequest:
      type: object
      description: A migration script to lint for unsafe schema changes.
      required:
        - sql
      properties:
        sql:
          type: string
          minLength: 1
          maxLength: 1048576
          description: The migration SQL to analyze. May contain multiple statements.
        database_id:
          type: string
          description: Optional database to scope the lint to.
    MigrationFinding:
      type: object
      description: A single issue found while linting a migration.
      required:
        - severity
        - rule
        - message
      properties:
        severity:
          type: string
          enum:
            - info
            - warning
            - error
          description: How serious the finding is. error indicates an unsafe change.
        rule:
          type: string
          description: Machine-readable rule identifier (e.g. drop_table, add_not_null_no_default).
        message:
          type: string
          description: Human-readable description of the issue.
        statement:
          type: string
          description: The statement that triggered the finding.
        hint:
          type: string
          description: Suggested safer alternative, if any.
    MigrationLintResponse:
      type: object
      description: Result of linting a migration script.
      required:
        - safe
        - findings
      properties:
        safe:
          type: boolean
          description: True when no error-severity findings were detected.
        findings:
          type: array
          description: Findings detected across all statements.
          items:
            $ref: '#/components/schemas/MigrationFinding'
    OnboardingProgress:
      type: object
      description: Progress state for the dashboard onboarding checklist.
      required:
        - organization_id
        - org_created
        - project_created
        - database_added
        - connection_tested
        - connection_string_copied
        - first_query_run
        - agent_credential_created
        - dismissed
        - completed
        - steps_completed
        - steps_total
      properties:
        organization_id:
          type: string
          description: Organization ID this onboarding belongs to.
        org_created:
          type: boolean
          description: Whether the organization has been created.
        project_created:
          type: boolean
          description: Whether a project has been created.
        database_added:
          type: boolean
          description: Whether a database has been added.
        connection_tested:
          type: boolean
          description: Whether the database connection has been tested.
        connection_string_copied:
          type: boolean
          description: Whether the connection string has been copied.
        first_query_run:
          type: boolean
          description: Whether the first query has been run through PgBeam.
        agent_credential_created:
          type: boolean
          description: Whether an agent credential has been issued.
        dismissed:
          type: boolean
          description: Whether the user has dismissed the onboarding checklist.
        completed:
          type: boolean
          description: Whether all onboarding steps are complete.
        steps_completed:
          type: integer
          description: Number of completed onboarding steps.
        steps_total:
          type: integer
          description: Total number of onboarding steps.
        completed_at:
          type: string
          format: date-time
          nullable: true
          description: When onboarding was completed. Null if not yet completed.
    UpdateOnboardingRequest:
      type: object
      description: Request body for advancing or dismissing onboarding.
      properties:
        step:
          type: string
          enum:
            - project_created
            - database_added
            - connection_tested
            - connection_string_copied
            - first_query_run
            - agent_credential_created
          description: The onboarding step to mark as complete.
          example: project_created
        dismiss:
          type: boolean
          description: Set to true to dismiss the onboarding checklist.
    OrganizationSummary:
      type: object
      description: An organization visible to the caller's credential.
      required:
        - id
        - name
        - slug
      properties:
        id:
          type: string
          description: Organization identifier.
          example: org_abc123
        name:
          type: string
          description: Organization display name.
          example: Acme Corp
        slug:
          type: string
          description: Organization slug used in URLs and routing.
          example: acme-corp
        role:
          type: string
          description: >-
            The caller's role within the organization. Omitted for organization-scoped API keys, which act as the
            organization itself rather than as a member.
          example: owner
    ListOrganizationsResponse:
      type: object
      description: Organizations visible to the caller's credential.
      required:
        - organizations
      properties:
        organizations:
          type: array
          description: Organizations the caller can access.
          items:
            $ref: '#/components/schemas/OrganizationSummary'
    PiiSuggestion:
      type: object
      description: >-
        A single likely-PII column detected by the scanner, with a recommended masking rule. Suggestions are advisory
        only — nothing is applied until the operator reviews and adds it to a policy profile.
      required:
        - schema
        - table
        - column
        - data_type
        - pii_type
        - mask_kind
        - confidence
        - reasons
      properties:
        schema:
          type: string
          description: Schema the column belongs to (e.g. "public").
          example: public
        table:
          type: string
          description: Table the column belongs to.
          example: users
        column:
          type: string
          description: The detected column name.
          example: email
        data_type:
          type: string
          description: PostgreSQL data type of the column.
          example: text
        pii_type:
          type: string
          enum:
            - email
            - phone
            - ssn
            - credit_card
            - ip_address
            - full_name
            - street_address
            - date_of_birth
            - national_id
            - passport
            - bank_account
            - api_secret
            - other
          description: The kind of personally identifiable information detected.
        mask_kind:
          type: string
          enum:
            - redact
            - 'null'
            - hash
          description: >-
            Recommended masking kind for this column. hash is suggested for join/group keys (e.g. email), redact for
            free-text PII, null for highly sensitive secrets.
        confidence:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: >-
            Confidence score in [0,1]. Combines column-name signal and sampled-value signal; higher is stronger
            evidence.
          example: 0.95
        reasons:
          type: array
          description: Human-readable explanations for why the column was flagged.
          items:
            type: string
          example:
            - column name matches 'email'
            - 8/10 sampled values look like emails
        sample_match_count:
          type: integer
          minimum: 0
          description: Number of sampled non-null values that matched the PII pattern.
        sample_size:
          type: integer
          minimum: 0
          description: Number of non-null values sampled from the column.
    ScanPiiResult:
      type: object
      description: Result of a PII detection scan over a database's schema.
      required:
        - scanned_columns
        - scanned_tables
        - suggestions
      properties:
        scanned_tables:
          type: integer
          minimum: 0
          description: Number of tables inspected.
        scanned_columns:
          type: integer
          minimum: 0
          description: Number of columns inspected.
        suggestions:
          type: array
          description: Ranked masking suggestions, highest confidence first. Empty when no likely-PII columns were found.
          items:
            $ref: '#/components/schemas/PiiSuggestion'
        truncated:
          type: boolean
          description: True when the scan stopped early at the column limit and some columns were not inspected.
        error:
          type: string
          description: Present when the scan failed to connect or read the schema.
    MaskingRule:
      type: object
      description: A column masking rule applied to agent query results.
      required:
        - table
        - column
        - kind
      properties:
        table:
          type: string
          description: Relation name, optionally schema-qualified (e.g. "public.users" or "users").
          example: users
        column:
          type: string
          description: Column to mask.
          example: email
        kind:
          type: string
          enum:
            - redact
            - 'null'
            - hash
          description: How to mask. redact replaces with a token, null returns NULL, hash returns a SHA-256 hex.
    RowFilter:
      type: object
      description: >-
        A per-relation row filter. The predicate is a raw SQL boolean expression ANDed into the WHERE clause for the
        matching relation.
      required:
        - table
        - predicate
      properties:
        table:
          type: string
          description: Relation name, optionally schema-qualified (e.g. "public.orders").
          example: orders
        predicate:
          type: string
          description: Raw SQL boolean expression ANDed into WHERE for this relation.
          example: tenant_id = current_setting('pgbeam.tenant')
    StatementRules:
      type: object
      description: Per-statement-kind allow/deny lists. Empty allow means all kinds permitted by the access mode.
      properties:
        allow:
          type: array
          description: Allowed statement kinds (select, insert, update, delete, ddl, copy, set, show, explain, transaction).
          items:
            type: string
            description: A statement kind.
        deny:
          type: array
          description: Denied statement kinds (takes precedence over allow).
          items:
            type: string
            description: A statement kind.
    PolicyProfile:
      type: object
      description: A named bundle of rules enforced on agent credentials in the data plane.
      required:
        - id
        - project_id
        - name
        - access_mode
        - table_allowlist
        - table_denylist
        - masking_rules
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: Unique policy profile identifier (prefixed).
          example: pol_01h455vb4pex5vsknk084sn02q
        project_id:
          type: string
          description: Owning project ID.
          example: prj_01h455vb4pex5vsknk084sn02q
        name:
          type: string
          description: Human-readable name for the policy profile.
          example: Read-only analytics
        access_mode:
          type: string
          enum:
            - read_only
            - read_write
          description: read_only blocks all data and schema mutations.
        statement_rules:
          $ref: '#/components/schemas/StatementRules'
        table_allowlist:
          type: array
          description: If non-empty, only these relations are reachable. Schema-qualified or bare names.
          items:
            type: string
            description: A relation name.
        table_denylist:
          type: array
          description: Relations explicitly blocked (takes precedence over the allowlist).
          items:
            type: string
            description: A relation name.
        masking_rules:
          type: array
          description: Column masking rules applied to query results.
          items:
            $ref: '#/components/schemas/MaskingRule'
        budget_queries_per_hour:
          type: integer
          description: Max queries per rolling hour window. 0 means unlimited.
          default: 0
        budget_queries_per_day:
          type: integer
          description: Max queries per day window. 0 means unlimited.
          default: 0
        max_rows:
          type: integer
          description: Max rows returned per query. 0 means unlimited.
          default: 0
        statement_timeout_ms:
          type: integer
          description: Upstream statement timeout for agent sessions. 0 uses the project default.
          default: 0
        row_filters:
          type: array
          description: Per-relation row filters ANDed into agent reads.
          items:
            $ref: '#/components/schemas/RowFilter'
        write_mode:
          type: string
          enum:
            - normal
            - rollback
            - sandbox
          default: normal
          description: How writes are handled. normal commits, rollback auto-rolls back, sandbox routes to an ephemeral branch.
        approval_mode:
          type: string
          enum:
            - 'off'
            - writes
            - ddl
            - all
          default: 'off'
          description: Which statement classes require human approval before execution.
        approval_auto_max_rows:
          type: integer
          minimum: 0
          default: 0
          description: Statements touching at most this many rows are auto-approved. 0 means none.
        approval_timeout_seconds:
          type: integer
          minimum: 0
          default: 300
          description: How long a held statement waits for a decision before expiring.
        migration_safety:
          type: string
          enum:
            - 'off'
            - warn
            - block
          default: 'off'
          description: Migration safety mode. warn surfaces findings, block refuses unsafe DDL.
        egress_bytes_per_day:
          type: integer
          format: int64
          minimum: 0
          default: 0
          description: Per-day egress budget in bytes. 0 means unlimited.
        max_affected_rows:
          type: integer
          minimum: 0
          default: 0
          description: >-
            Hard cap on rows a single write (INSERT/UPDATE/DELETE) may affect. A write whose affected-row count would
            exceed this is executed inside a transaction, checked, and rolled back so nothing persists, then blocked.
            Enforced independently of human approval. 0 means unlimited.
        created_at:
          type: string
          format: date-time
          description: When the policy profile was created.
        updated_at:
          type: string
          format: date-time
          description: When the policy profile was last updated.
    PolicyProfileInput:
      type: object
      description: Mutable fields of a policy profile (used for create and update).
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 128
          description: Human-readable name for the policy profile.
        access_mode:
          type: string
          enum:
            - read_only
            - read_write
          default: read_only
          description: read_only blocks all data and schema mutations.
        statement_rules:
          $ref: '#/components/schemas/StatementRules'
        table_allowlist:
          type: array
          description: If non-empty, only these relations are reachable.
          items:
            type: string
            description: A relation name.
        table_denylist:
          type: array
          description: Relations explicitly blocked.
          items:
            type: string
            description: A relation name.
        masking_rules:
          type: array
          description: Column masking rules applied to query results.
          items:
            $ref: '#/components/schemas/MaskingRule'
        budget_queries_per_hour:
          type: integer
          minimum: 0
          default: 0
          description: Max queries per rolling hour window. 0 means unlimited.
        budget_queries_per_day:
          type: integer
          minimum: 0
          default: 0
          description: Max queries per day window. 0 means unlimited.
        max_rows:
          type: integer
          minimum: 0
          default: 0
          description: Max rows returned per query. 0 means unlimited.
        statement_timeout_ms:
          type: integer
          minimum: 0
          default: 0
          description: Upstream statement timeout for agent sessions. 0 uses the project default.
        row_filters:
          type: array
          description: Per-relation row filters ANDed into agent reads.
          items:
            $ref: '#/components/schemas/RowFilter'
        write_mode:
          type: string
          enum:
            - normal
            - rollback
            - sandbox
          default: normal
          description: How writes are handled. normal commits, rollback auto-rolls back, sandbox routes to an ephemeral branch.
        approval_mode:
          type: string
          enum:
            - 'off'
            - writes
            - ddl
            - all
          default: 'off'
          description: Which statement classes require human approval before execution.
        approval_auto_max_rows:
          type: integer
          minimum: 0
          default: 0
          description: Statements touching at most this many rows are auto-approved. 0 means none.
        approval_timeout_seconds:
          type: integer
          minimum: 0
          default: 300
          description: How long a held statement waits for a decision before expiring.
        migration_safety:
          type: string
          enum:
            - 'off'
            - warn
            - block
          default: 'off'
          description: Migration safety mode. warn surfaces findings, block refuses unsafe DDL.
        egress_bytes_per_day:
          type: integer
          format: int64
          minimum: 0
          default: 0
          description: Per-day egress budget in bytes. 0 means unlimited.
        max_affected_rows:
          type: integer
          minimum: 0
          default: 0
          description: >-
            Hard cap on rows a single write (INSERT/UPDATE/DELETE) may affect. A write whose affected-row count would
            exceed this is executed inside a transaction, checked, and rolled back so nothing persists, then blocked.
            Enforced independently of human approval. 0 means unlimited.
    ListPolicyProfilesResponse:
      type: object
      description: Cursor-paginated list of policy profiles for a project.
      required:
        - policies
      properties:
        policies:
          type: array
          description: Policy profiles on the current page.
          items:
            $ref: '#/components/schemas/PolicyProfile'
        next_page_token:
          type: string
          description: Token for the next page. Empty if no more results.
    DryEvalInput:
      type: object
      description: >-
        A SQL statement to test plus the policy to test it against. Supply exactly one of policy_id (an existing saved
        policy) or policy (an unsaved draft, e.g. the in-progress editor form).
      required:
        - sql
      properties:
        sql:
          type: string
          minLength: 1
          maxLength: 100000
          description: The single SQL statement to evaluate.
          example: SELECT email FROM users WHERE id = 1
        policy_id:
          type: string
          description: ID of an existing saved policy profile to evaluate against.
          example: pol_01h455vb4pex5vsknk084sn02q
        policy:
          $ref: '#/components/schemas/PolicyProfileInput'
    PolicyReplayInput:
      type: object
      description: >-
        A window of recorded agent traffic to replay plus the candidate policy to replay it against. Supply exactly one
        of policy_id (an existing saved policy) or policy (an unsaved draft, e.g. the in-progress editor form).
      properties:
        policy_id:
          type: string
          description: ID of an existing saved policy profile to replay against.
          example: pol_01h455vb4pex5vsknk084sn02q
        policy:
          $ref: '#/components/schemas/PolicyProfileInput'
        credential_id:
          type: string
          description: Restrict the replay to traffic recorded for one agent credential.
          example: cred_01h455vb4pex5vsknk084sn02q
        start_ts:
          type: string
          format: date-time
          description: Start of the traffic window (inclusive). Defaults to 7 days before end_ts.
        end_ts:
          type: string
          format: date-time
          description: End of the traffic window (exclusive). Defaults to now.
        limit:
          type: integer
          minimum: 1
          maximum: 500
          default: 200
          description: >-
            Maximum number of distinct queries to replay, newest first. Traffic is deduplicated by normalized query hash
            before evaluation.
    PolicyReplaySummary:
      type: object
      description: Aggregate outcome of a policy replay.
      required:
        - entries_scanned
        - distinct_queries
        - evaluated
        - would_allow
        - would_block
        - would_mask
        - would_row_filter
        - newly_blocked
        - newly_allowed
        - skipped_unparseable
        - truncated
      properties:
        entries_scanned:
          type: integer
          format: int64
          description: Recorded audit entries covered by the replayed queries.
        distinct_queries:
          type: integer
          description: Distinct normalized queries found in the window (capped at limit).
        evaluated:
          type: integer
          description: Distinct queries actually evaluated against the candidate policy.
        would_allow:
          type: integer
          description: Queries the candidate policy would allow unchanged.
        would_block:
          type: integer
          description: Queries the candidate policy would block.
        would_mask:
          type: integer
          description: Queries the candidate policy would mask result columns on.
        would_row_filter:
          type: integer
          description: Queries the candidate policy would inject a row filter into.
        newly_blocked:
          type: integer
          description: Queries that executed under the recorded policy but the candidate policy would block.
        newly_allowed:
          type: integer
          description: Queries that were blocked when recorded but the candidate policy would permit.
        skipped_unparseable:
          type: integer
          description: >-
            Distinct queries skipped because the stored statement was truncated at record time and can no longer be
            parsed faithfully.
        truncated:
          type: boolean
          description: True when the window contained more distinct queries than limit; only the newest were replayed.
    PolicyReplayItem:
      type: object
      description: One distinct recorded query and the decision the candidate policy would reach for it.
      required:
        - query_hash
        - sql
        - occurrences
        - first_seen
        - last_seen
        - recorded_event
        - change
        - result
      properties:
        query_hash:
          type: string
          description: Normalized query hash identifying this statement shape.
        sql:
          type: string
          description: >-
            The recorded statement (normalized, literals replaced with $N placeholders), from its most recent
            occurrence.
        statement_kind:
          type: string
          description: Statement kind (select, insert, update, delete, ddl, ...).
        occurrences:
          type: integer
          format: int64
          description: How many recorded entries share this query shape in the window.
        first_seen:
          type: string
          format: date-time
          description: Oldest occurrence in the window.
        last_seen:
          type: string
          format: date-time
          description: Newest occurrence in the window.
        recorded_event:
          type: string
          description: The most recent recorded outcome for this query (query, masked, truncated, or blocked).
        recorded_rule:
          type: string
          description: The decision rule recorded with a blocked outcome.
        change:
          type: string
          enum:
            - newly_blocked
            - newly_allowed
            - still_allowed
            - still_blocked
          description: >-
            How the candidate decision compares to the recorded outcome. newly_blocked and newly_allowed are the changes
            worth reviewing before rollout; still_allowed and still_blocked are unchanged.
        result:
          $ref: '#/components/schemas/DryEvalResult'
    PolicyReplayResult:
      type: object
      description: >-
        The outcome of replaying recorded agent traffic against a candidate policy: an aggregate summary plus per-query
        decisions, changes first.
      required:
        - summary
        - items
      properties:
        summary:
          $ref: '#/components/schemas/PolicyReplaySummary'
        items:
          type: array
          description: >-
            Per-query replay decisions, ordered changes first (newly blocked, then newly allowed), then by occurrence
            count.
          items:
            $ref: '#/components/schemas/PolicyReplayItem'
    PolicyRecommendationInput:
      type: object
      description: >-
        Optional parameters for a least-privilege policy recommendation. Every field is optional; an empty body analyzes
        the last 30 days of the credential's audit history.
      properties:
        lookback_days:
          type: integer
          minimum: 1
          maximum: 365
          default: 30
          description: How many days of recorded audit history to analyze.
        limit:
          type: integer
          minimum: 1
          maximum: 500
          default: 200
          description: >-
            Maximum number of distinct query shapes to analyze and replay, newest first. Traffic is deduplicated by
            normalized query hash.
    PolicyRecommendation:
      type: object
      description: >-
        A least-privilege policy derived from an agent credential's recorded audit history, together with the replay
        diff that proves the candidate would not newly block any statement the credential legitimately ran. Advisory
        only: this endpoint never creates, updates, or otherwise mutates a policy or a credential. A good recommendation
        has replay.summary.newly_blocked == 0.
      required:
        - sufficient_history
        - observed_queries
        - observed_entries
        - window_start
        - window_end
      properties:
        sufficient_history:
          type: boolean
          description: >-
            True when there was enough parseable, executed traffic to derive a candidate. When false, candidate and
            replay are omitted and message explains why no recommendation could be made.
        message:
          type: string
          description: >-
            Present when sufficient_history is false; a clear explanation of why no recommendation could be produced
            (e.g. no executed traffic in the window).
        candidate:
          $ref: '#/components/schemas/PolicyProfileInput'
        replay:
          $ref: '#/components/schemas/PolicyReplayResult'
        observed_queries:
          type: integer
          description: >-
            Distinct executed query shapes the candidate was derived from (blocked attempts are excluded from
            derivation).
        observed_entries:
          type: integer
          format: int64
          description: Recorded audit entries covered by the analyzed window.
        window_start:
          type: string
          format: date-time
          description: Start of the analyzed traffic window (inclusive).
        window_end:
          type: string
          format: date-time
          description: End of the analyzed traffic window (exclusive).
        notes:
          type: array
          description: >-
            Human-readable rationale for each tightening decision (e.g. why the candidate was downgraded to read-only,
            or how max_rows was chosen).
          items:
            type: string
    DryEvalMaskedColumn:
      type: object
      description: One result column that would be masked, with the mask kind applied.
      required:
        - column
        - kind
      properties:
        column:
          type: string
          description: The output column name (post-alias) the client would see masked.
          example: email
        kind:
          type: string
          enum:
            - redact
            - 'null'
            - hash
          description: How the column is masked.
    DryEvalResult:
      type: object
      description: >-
        The decision the proxy would reach for the supplied statement under the supplied policy. verdict is the headline
        outcome; the remaining fields detail why.
      required:
        - verdict
        - rule
        - reason
      properties:
        verdict:
          type: string
          enum:
            - allow
            - block
            - mask
            - row-filter
          description: >-
            allow — permitted unchanged; block — rejected; mask — permitted but listed result columns are masked;
            row-filter — permitted but a WHERE predicate is injected (and any listed columns are also masked).
        rule:
          type: string
          description: >-
            Machine-readable decision tag. For a block, the blocking rule (e.g. read_only, table_denied,
            table_not_allowed, statement_denied, row_filter_unsafe). Otherwise "ok".
          example: ok
        reason:
          type: string
          description: Human-readable explanation of the verdict.
        hint:
          type: string
          description: What the author could do instead (present on block verdicts).
        masked_columns:
          type: array
          description: Result columns that would be masked. Present on mask/row-filter verdicts.
          items:
            $ref: '#/components/schemas/DryEvalMaskedColumn'
        row_filter_predicate:
          type: string
          description: The row-filter predicate ANDed into the statement's WHERE clause.
          example: tenant_id = current_setting('pgbeam.tenant')
        rewritten_sql:
          type: string
          description: The statement as it would be sent upstream after row-filter injection.
        notes:
          type: array
          description: >-
            Informational caveats about stateful enforcement a single-statement preview cannot model (per-region
            budgets, approvals, write-mode routing).
          items:
            type: string
    Project:
      type: object
      description: Project configuration and current control-plane state.
      required:
        - id
        - org_id
        - name
        - status
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: Unique project identifier (prefixed).
          example: prj_01h455vb4pex5vsknk084sn02q
        org_id:
          type: string
          description: Better Auth organization ID that owns this project.
          example: org_abc123
        name:
          type: string
          description: Human-readable project name.
          minLength: 1
          maxLength: 100
          example: my-app
        description:
          type: string
          description: Optional project description.
          maxLength: 500
          example: Production database proxy
        tags:
          type: array
          description: User-defined labels applied to the project.
          maxItems: 10
          example:
            - production
            - us-east-1
          items:
            type: string
            maxLength: 50
        cloud:
          type: string
          enum:
            - aws
            - azure
            - gcp
          description: Cloud provider where the project runs.
          readOnly: true
        self_hosted:
          type: boolean
          description: >
            When true, this project's data plane runs in the customer's own VPC/cluster (BYOC): the control plane does
            not provision hosted infra, and a self-hosted proxy dials home over the config/audit gRPC stream. Requires
            the Scale or enterprise plan.
          readOnly: true
          example: false
        proxy_host:
          type: string
          description: Proxy hostname for connecting through PgBeam (e.g., myproject.proxy.pgbeam.app).
          readOnly: true
        queries_per_second:
          type: integer
          format: int32
          minimum: 0
          maximum: 2147483647
          description: Maximum queries per second for this project. 0 means unlimited.
          readOnly: true
          example: 1000
        burst_size:
          type: integer
          format: int32
          minimum: 0
          maximum: 2147483647
          description: Burst allowance above the steady-state rate. 0 uses queries_per_second as burst.
          readOnly: true
          example: 200
        max_connections:
          type: integer
          format: int32
          minimum: 0
          maximum: 2147483647
          description: Maximum concurrent proxy connections. 0 means unlimited.
          readOnly: true
          example: 500
        allowed_cidrs:
          type: array
          description: >
            IP filtering rules as CIDR ranges with optional labels. When non-empty, only connections from matching IPs
            are accepted. Empty array means all IPs are allowed (default). Both IPv4 (e.g. 10.0.0.0/8) and IPv6 (e.g.
            2001:db8::/32) are supported.
          example:
            - cidr: 10.0.0.0/8
              label: VPC
            - cidr: 2001:db8::/32
              label: IPv6 range
          items:
            $ref: '#/components/schemas/CidrEntry'
          maxItems: 50
        default_policy_profile_id:
          type: string
          nullable: true
          description: When set, passthrough/human connections are enforced against this policy profile.
          example: pol_01h455vb4pex5vsknk084sn02q
        residency:
          $ref: '#/components/schemas/DataResidency'
        agents_disabled:
          type: boolean
          description: >
            Project-level kill-switch. When true, ALL agent-credential connections to this project are blocked at the
            proxy and live agent sessions are dropped within seconds. Passthrough/human connections are unaffected.
          example: false
        database_count:
          type: integer
          description: Number of databases attached to this project.
          readOnly: true
        active_connections:
          type: integer
          description: Current active connections (latest metrics snapshot). 0 when no metrics data.
          readOnly: true
        status:
          $ref: '#/components/schemas/ProjectStatus'
        created_at:
          type: string
          format: date-time
          description: When the project was created.
        updated_at:
          type: string
          format: date-time
          description: When the project was last updated.
    ProjectStatus:
      type: string
      enum:
        - active
        - suspended
        - deleted
      description: Project lifecycle status.
    DataResidency:
      type: string
      enum:
        - any
        - us
        - eu
      default: any
      description: >
        Data-residency requirement for the project. "any" (default) lets queries be served from the nearest data-plane
        metro. "us" or "eu" require the serving metro to be in that jurisdiction; the proxy fails a connection closed
        when it is served from a metro outside the required jurisdiction, so regulated workloads never process outside
        their permitted region.
      example: eu
    CreateProjectRequest:
      type: object
      description: Request body for creating a project and its primary database, which are created atomically.
      required:
        - name
        - org_id
        - database
      properties:
        name:
          type: string
          description: Human-readable project name.
          minLength: 1
          maxLength: 100
          pattern: ^[^\x00]*$
          example: my-app
        org_id:
          type: string
          minLength: 1
          pattern: ^[^\x00]+$
          description: Better Auth organization ID.
          example: org_abc123
        description:
          type: string
          description: Optional project description.
          maxLength: 500
          example: Production database proxy
        tags:
          type: array
          description: User-defined labels to attach to the project.
          maxItems: 10
          example:
            - production
            - us-east-1
          items:
            type: string
            maxLength: 50
        cloud:
          type: string
          enum:
            - aws
            - azure
            - gcp
          description: Cloud provider for the project.
          default: aws
        self_hosted:
          type: boolean
          description: >
            Mark this project as running on a self-hosted (BYOC) data plane in the customer's own VPC/cluster. Requires
            the Scale or enterprise plan.
          default: false
        database:
          $ref: '#/components/schemas/CreateDatabaseRequest'
    CreateProjectResponse:
      type: object
      description: Response returned after creating a project and its primary database.
      required:
        - project
      properties:
        project:
          $ref: '#/components/schemas/Project'
        database:
          $ref: '#/components/schemas/Database'
    UpdateProjectRequest:
      type: object
      description: Request body for partially updating a project.
      properties:
        name:
          type: string
          description: Updated project name.
          minLength: 1
          maxLength: 100
          pattern: ^[^\x00]*$
          example: my-app
        description:
          type: string
          description: Updated project description.
          maxLength: 500
          example: Production database proxy
        tags:
          type: array
          description: Replacement set of user-defined project labels.
          maxItems: 10
          example:
            - production
            - us-east-1
          items:
            type: string
            maxLength: 50
        status:
          $ref: '#/components/schemas/ProjectStatus'
        allowed_cidrs:
          type: array
          description: >
            IP filtering rules as CIDR ranges with optional labels. Empty array means allow all. Both IPv4 and IPv6 CIDR
            notation are supported.
          example:
            - cidr: 10.0.0.0/8
              label: VPC
            - cidr: 203.0.113.5/32
              label: Office
          items:
            $ref: '#/components/schemas/CidrEntry'
          maxItems: 50
        default_policy_profile_id:
          type: string
          nullable: true
          description: >
            When set, passthrough/human connections are enforced against this policy profile. Send an empty string to
            clear.
          example: pol_01h455vb4pex5vsknk084sn02q
        residency:
          $ref: '#/components/schemas/DataResidency'
        agents_disabled:
          type: boolean
          description: >
            Project-level kill-switch. Set true to block ALL agent-credential connections to this project (live agent
            sessions are dropped within seconds); set false to re-enable them. Passthrough/human connections are
            unaffected. Engaging the kill-switch emits a kill_switch webhook event.
          example: true
    ListProjectsResponse:
      type: object
      description: Cursor-paginated list of projects for an organization.
      required:
        - projects
        - total
      properties:
        projects:
          type: array
          description: Projects on the current page.
          items:
            $ref: '#/components/schemas/Project'
        total:
          type: integer
          description: Total number of projects (across all pages).
        next_page_token:
          type: string
          description: Token for the next page. Empty if no more results.
    CidrEntry:
      type: object
      description: An IP filtering rule with a CIDR range and optional human-readable label.
      required:
        - cidr
      properties:
        cidr:
          type: string
          description: >
            CIDR range in IPv4 (e.g. 203.0.113.0/24) or IPv6 (e.g. 2001:db8::/32) notation. A plain IP without prefix
            length defaults to /32 (IPv4) or /128 (IPv6).
          pattern: ^[0-9a-fA-F.:]+(/[0-9]+)?$
          example: 10.0.0.0/8
        label:
          type: string
          description: Optional human-readable label for this CIDR entry (e.g. "Office", "VPC").
          maxLength: 100
          example: Office network
    Region:
      type: object
      description: Data plane region available for PgBeam traffic.
      required:
        - id
        - name
        - provider
        - status
        - available
      properties:
        id:
          type: string
          description: Region identifier (e.g. us-east-1).
          example: us-east-1
        name:
          type: string
          description: Human-readable region name.
          example: US East (N. Virginia)
        provider:
          type: string
          enum:
            - aws
            - azure
            - gcp
          description: Cloud provider.
          example: aws
        status:
          type: string
          enum:
            - active
            - draining
            - inactive
          description: Region operational status.
        available:
          type: boolean
          description: Whether new projects can currently be assigned to the region.
        continent:
          type: string
          description: Continent where the region is located.
        country:
          type: string
          description: Country where the region is located.
    ListRegionsResponse:
      type: object
      description: Response envelope for available region queries.
      required:
        - regions
      properties:
        regions:
          type: array
          description: Regions currently known to the control plane.
          items:
            $ref: '#/components/schemas/Region'
    Replica:
      type: object
      description: Read replica registered for a primary database.
      required:
        - id
        - database_id
        - host
        - port
        - ssl_mode
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: Unique replica identifier (prefixed).
          example: rep_01h455vb4pex5vsknk084sn02q
        database_id:
          type: string
          description: Parent database ID.
          example: db_01h455vb4pex5vsknk084sn02q
        host:
          type: string
          description: PostgreSQL replica host.
          example: replica.db.example.com
        port:
          type: integer
          minimum: 1
          maximum: 65535
          description: PostgreSQL replica port.
          example: 5432
        ssl_mode:
          $ref: '#/components/schemas/SSLMode'
        created_at:
          type: string
          format: date-time
          description: When the replica was created.
        updated_at:
          type: string
          format: date-time
          description: When the replica was last updated.
    CreateReplicaRequest:
      type: object
      description: Request body for adding a read replica to a database.
      required:
        - host
        - port
      properties:
        host:
          type: string
          minLength: 1
          pattern: ^[^\s\x00]+$
          description: PostgreSQL replica host.
          example: replica.us-west-2.rds.amazonaws.com
        port:
          type: integer
          minimum: 1
          maximum: 65535
          description: PostgreSQL replica port.
          example: 5432
        ssl_mode:
          $ref: '#/components/schemas/SSLMode'
    ListReplicasResponse:
      type: object
      description: Response envelope for listing registered replicas.
      required:
        - replicas
      properties:
        replicas:
          type: array
          description: Read replicas attached to the database.
          items:
            $ref: '#/components/schemas/Replica'
        next_page_token:
          type: string
          description: Opaque token for cursor-based pagination.
    SchemaAnnotation:
      type: object
      description: >
        A human-written description for a table or column, attached by a project operator and surfaced through the
        agent-facing MCP catalog. When present it takes precedence over the DB-native comment for the same relation or
        column.
      required:
        - id
        - project_id
        - table_name
        - description
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: Unique annotation identifier.
          example: sca_01j9x8y7z6w5v4u3t2s1r0q9p8
        project_id:
          type: string
          description: Project the annotation belongs to.
          example: prj_01j9x8y7z6w5v4u3t2s1r0q9p8
        schema_name:
          type: string
          nullable: true
          description: |
            Optional schema. Null matches the unqualified form, mirroring the relation allowlist normalization.
          example: public
        table_name:
          type: string
          description: Relation (table or view) the annotation describes.
          example: users
        column_name:
          type: string
          nullable: true
          description: |
            Optional column. Null means the annotation describes the table itself.
          example: email
        description:
          type: string
          description: The operator-written description text.
          example: Primary customer account. One row per signed-up user.
        created_at:
          type: string
          format: date-time
          description: When the annotation was created.
        updated_at:
          type: string
          format: date-time
          description: When the annotation was last updated.
    SchemaAnnotationInput:
      type: object
      description: >
        Request body for creating or replacing a schema annotation. Keyed by (schema_name, table_name, column_name); an
        existing annotation with the same key is replaced.
      required:
        - table_name
        - description
      properties:
        schema_name:
          type: string
          nullable: true
          maxLength: 255
          description: Optional schema. Null or empty matches the unqualified form.
          example: public
        table_name:
          type: string
          minLength: 1
          maxLength: 255
          description: Relation (table or view) the annotation describes.
          example: users
        column_name:
          type: string
          nullable: true
          maxLength: 255
          description: Optional column. Null describes the table itself.
          example: email
        description:
          type: string
          minLength: 1
          maxLength: 4096
          description: The operator-written description text.
          example: Primary customer account. One row per signed-up user.
    ListSchemaAnnotationsResponse:
      type: object
      description: Cursor-paginated schema annotations for a project.
      required:
        - annotations
      properties:
        annotations:
          type: array
          description: Annotations returned for the current page.
          items:
            $ref: '#/components/schemas/SchemaAnnotation'
        next_page_token:
          type: string
          description: Opaque token for cursor-based pagination.
    SchemaCatalogColumn:
      type: object
      description: One column of a relation in the schema catalog.
      required:
        - name
        - data_type
        - is_binary
      properties:
        name:
          type: string
          description: Column name.
          example: email
        data_type:
          type: string
          description: PostgreSQL data type (information_schema.data_type).
          example: text
        is_binary:
          type: boolean
          description: >-
            True for binary-typed columns (e.g. bytea). Masking a binary column always returns NULL — a redact/hash
            token would corrupt the wire type — so the editor warns when a masking rule targets one.
    SchemaCatalogRelation:
      type: object
      description: One relation (base table or view) in the schema catalog.
      required:
        - schema
        - name
        - kind
        - columns
      properties:
        schema:
          type: string
          description: Schema the relation belongs to.
          example: public
        name:
          type: string
          description: Relation name.
          example: users
        kind:
          type: string
          enum:
            - table
            - view
            - materialized_view
            - other
          description: >-
            Relation kind. Allowlists, masking, and row-filters are enforced against the named relation itself, NOT
            through a view to its base tables — so a view over a row-filtered base table can leak. The editor warns when
            a policy entry targets a view.
        columns:
          type: array
          description: The relation's columns.
          items:
            $ref: '#/components/schemas/SchemaCatalogColumn'
    SchemaCatalog:
      type: object
      description: >-
        A read-only snapshot of a database's user relations (tables and views) and their columns, used to power
        table/column autocomplete and view-aware warnings in the policy editor. System schemas (pg_catalog,
        information_schema, pg_toast) are excluded.
      required:
        - relations
        - scanned_relations
        - scanned_columns
      properties:
        relations:
          type: array
          description: User relations, ordered by schema then name.
          items:
            $ref: '#/components/schemas/SchemaCatalogRelation'
        scanned_relations:
          type: integer
          minimum: 0
          description: Number of relations in the catalog.
        scanned_columns:
          type: integer
          minimum: 0
          description: Number of columns in the catalog.
        truncated:
          type: boolean
          description: True when the catalog stopped early at the column limit.
        error:
          type: string
          description: Present when introspection failed to connect or read the schema.
    SelfHostEnrollment:
      type: object
      description: >
        An enrollment that lets a self-hosted (BYOC) proxy authenticate to the control plane's config/audit gRPC stream
        on behalf of an organization. The token itself is never returned after creation, only its metadata.
      required:
        - id
        - org_id
        - created_at
      properties:
        id:
          type: string
          description: Unique enrollment identifier.
          example: she_01h455vb4pex5vsknk084sn02q
        org_id:
          type: string
          description: Organization that owns this enrollment.
          example: org_abc123
        region_label:
          type: string
          description: Operator-supplied label for where the proxy runs (informational).
          example: customer-vpc-us-east
        description:
          type: string
          description: Optional human-readable note.
          example: prod cluster
        created_by:
          type: string
          nullable: true
          description: User ID that created the enrollment.
        created_at:
          type: string
          format: date-time
          description: When the enrollment was created.
        last_seen_at:
          type: string
          format: date-time
          nullable: true
          description: Last time a proxy authenticated with this enrollment.
        revoked_at:
          type: string
          format: date-time
          nullable: true
          description: When the enrollment was revoked. Null means active.
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            When the enrollment token expires and stops authenticating new proxy connections. Null means it never
            expires. Enforcement is fail-closed at the gRPC auth gate the instant this time passes.
    SelfHostEnrollmentSecret:
      type: object
      description: >
        Response returned once when an enrollment is created or its token is rotated. The token is shown a single time
        and cannot be retrieved again; set it as GRPC_AUTH_TOKEN on the self-hosted proxy.
      required:
        - enrollment
        - token
      properties:
        enrollment:
          $ref: '#/components/schemas/SelfHostEnrollment'
        token:
          type: string
          description: The plaintext enrollment token (pbh_...). Shown once.
          example: pbh_01h455vb4pex5vsknk084sn02q9zk3m7
    CreateSelfHostEnrollmentRequest:
      type: object
      description: Request body for issuing a self-host enrollment token.
      properties:
        region_label:
          type: string
          description: Operator-supplied label for where the proxy runs.
          maxLength: 100
          pattern: ^[^\x00]*$
          example: customer-vpc-us-east
        description:
          type: string
          description: Optional human-readable note.
          maxLength: 500
          pattern: ^[^\x00]*$
          example: prod cluster
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            Optional expiry. When set, the enrollment token stops authenticating new proxy connections at this time
            (must be in the future). Omit or set null for a token that never expires.
    ListSelfHostEnrollmentsResponse:
      type: object
      description: List of self-host enrollments for an organization.
      required:
        - enrollments
      properties:
        enrollments:
          type: array
          description: The organization's self-host enrollments, newest first.
          items:
            $ref: '#/components/schemas/SelfHostEnrollment'
    SupportCase:
      type: object
      description: A support case filed by an organization member.
      required:
        - id
        - case_number
        - org_id
        - user_id
        - title
        - severity
        - status
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: Unique support case identifier (prefixed).
          example: sc_01h455vb4pex5vsknk084sn02q
        case_number:
          type: integer
          description: Human-readable sequential case number.
          readOnly: true
        org_id:
          type: string
          description: Organization that owns this case.
        user_id:
          type: string
          description: User who created the case.
        title:
          type: string
          description: Brief summary of the issue.
        severity:
          type: integer
          minimum: 1
          maximum: 4
          description: 'Severity level: 1=Critical, 2=High, 3=Normal, 4=Low.'
        status:
          $ref: '#/components/schemas/SupportCaseStatus'
        slack_channel_id:
          type: string
          description: Slack channel where the case thread lives.
        slack_thread_ts:
          type: string
          description: Slack thread timestamp for the case.
        created_at:
          type: string
          format: date-time
          description: When the case was created.
        updated_at:
          type: string
          format: date-time
          description: When the case was last updated.
        closed_at:
          type: string
          format: date-time
          nullable: true
          description: When the case was closed, if applicable.
        message_count:
          type: integer
          format: int64
          description: Number of messages in the case.
          readOnly: true
    SupportCaseStatus:
      type: string
      enum:
        - open
        - closed
      description: Current status of the support case.
    SupportMessage:
      type: object
      description: A message within a support case thread.
      required:
        - id
        - case_id
        - source
        - author_name
        - body
        - created_at
      properties:
        id:
          type: string
          description: Unique message identifier (prefixed).
          example: sm_01h455vb4pex5vsknk084sn02q
        case_id:
          type: string
          description: Parent support case ID.
        source:
          $ref: '#/components/schemas/SupportMessageSource'
        author_name:
          type: string
          description: Display name of the message author.
        author_image:
          type: string
          description: URL to the author's avatar.
          nullable: true
        body:
          type: string
          description: Message content.
        slack_user_id:
          type: string
          description: Slack user ID (for Slack-sourced messages).
          nullable: true
        created_at:
          type: string
          format: date-time
          description: When the message was created.
    SupportMessageSource:
      type: string
      enum:
        - user
        - slack
      description: Origin of the message.
    CreateSupportCaseRequest:
      type: object
      description: Request body for creating a support case.
      required:
        - org_id
        - title
        - body
      properties:
        org_id:
          type: string
          description: Organization ID.
        title:
          type: string
          description: Brief summary of the issue.
          minLength: 1
          maxLength: 500
        severity:
          type: integer
          minimum: 1
          maximum: 4
          default: 4
          description: 'Severity level: 1=Critical, 2=High, 3=Normal, 4=Low.'
        body:
          type: string
          description: Initial message body.
          minLength: 1
          maxLength: 50000
    UpdateSupportCaseRequest:
      type: object
      description: Request body for updating a support case status.
      properties:
        status:
          $ref: '#/components/schemas/SupportCaseStatus'
    CreateSupportMessageRequest:
      type: object
      description: Request body for adding a message to a support case.
      required:
        - body
      properties:
        body:
          type: string
          description: Message content.
          minLength: 1
          maxLength: 50000
    ListSupportCasesResponse:
      type: object
      description: Paginated list of support cases.
      required:
        - cases
        - total
      properties:
        cases:
          type: array
          description: Support cases for the current page.
          items:
            $ref: '#/components/schemas/SupportCase'
        total:
          type: integer
          format: int64
          description: Total number of cases matching the filter.
    GetSupportCaseResponse:
      type: object
      description: Support case with its message thread.
      required:
        - case
        - messages
      properties:
        case:
          $ref: '#/components/schemas/SupportCase'
        messages:
          type: array
          description: Messages in the support case thread.
          items:
            $ref: '#/components/schemas/SupportMessage'
    SlackEventPayload:
      type: object
      description: Slack event forwarded from the dashboard webhook handler.
      required:
        - channel_id
        - thread_ts
        - user_id
        - text
      properties:
        channel_id:
          type: string
          description: Slack channel ID where the message was posted.
        thread_ts:
          type: string
          description: Slack thread timestamp identifying the support case thread.
        user_id:
          type: string
          description: Slack user ID of the message author.
        text:
          type: string
          description: Message text from Slack.
    ProjectMetricsResponse:
      type: object
      description: Response envelope for recent project metrics snapshots.
      required:
        - snapshots
      properties:
        snapshots:
          type: array
          description: Metrics snapshots ordered from newest to oldest.
          items:
            $ref: '#/components/schemas/MetricsSnapshot'
    MetricsSnapshot:
      type: object
      description: Aggregated project metrics captured for a point in time.
      required:
        - id
        - project_id
        - region
        - queries_total
        - cache_hits
        - cache_misses
        - active_connections
        - avg_latency_ms
        - p99_latency_ms
        - created_at
      properties:
        id:
          type: string
          description: Unique metrics snapshot identifier.
        project_id:
          type: string
          description: Project that produced the metrics snapshot.
        region:
          type: string
          description: Region where the traffic was served.
        queries_total:
          type: integer
          format: int64
          description: Total queries served during the snapshot interval.
        cache_hits:
          type: integer
          format: int64
          description: Number of queries served from cache.
        cache_misses:
          type: integer
          format: int64
          description: Number of queries forwarded upstream.
        active_connections:
          type: integer
          description: Current active proxy connections.
        avg_latency_ms:
          type: number
          format: double
          description: Average end-to-end query latency in milliseconds.
        p99_latency_ms:
          type: number
          format: double
          description: 99th percentile end-to-end query latency in milliseconds.
        avg_connect_ms:
          type: number
          format: double
          description: Average upstream connection acquisition latency in milliseconds.
        avg_query_ms:
          type: number
          format: double
          description: Average upstream query execution latency in milliseconds.
        created_at:
          type: string
          format: date-time
          description: When the snapshot was recorded.
    UsageResponse:
      type: object
      description: Response envelope for organization usage queries.
      required:
        - usage
      properties:
        usage:
          type: array
          description: Daily usage entries aggregated across the organization.
          items:
            $ref: '#/components/schemas/DailyUsage'
    ProjectUsageResponse:
      type: object
      description: Response envelope for project usage queries.
      required:
        - usage
      properties:
        usage:
          type: array
          description: Daily usage entries grouped by region for the project.
          items:
            $ref: '#/components/schemas/ProjectDailyUsage'
    DailyUsage:
      type: object
      description: Daily usage totals aggregated across all projects in an organization.
      required:
        - day
        - queries_total
        - cache_hits
        - cache_misses
        - connection_seconds
        - bytes_transferred
      properties:
        day:
          type: string
          format: date
          description: Usage date in UTC.
        queries_total:
          type: integer
          format: int64
          description: Total queries served on the day.
        cache_hits:
          type: integer
          format: int64
          description: Total cache hits on the day.
        cache_misses:
          type: integer
          format: int64
          description: Total cache misses on the day.
        connection_seconds:
          type: integer
          format: int64
          description: Total proxy connection time consumed on the day.
        bytes_transferred:
          type: integer
          format: int64
          description: Total bytes transferred to clients.
    ProjectDailyUsage:
      type: object
      description: Daily usage totals for a single project and region.
      required:
        - day
        - region
        - queries_total
        - cache_hits
        - cache_misses
        - connection_seconds
        - bytes_transferred
      properties:
        day:
          type: string
          format: date
          description: Usage date in UTC.
        region:
          type: string
          description: Region where the traffic was served.
        queries_total:
          type: integer
          format: int64
          description: Total queries served on the day.
        cache_hits:
          type: integer
          format: int64
          description: Total cache hits on the day.
        cache_misses:
          type: integer
          format: int64
          description: Total cache misses on the day.
        connection_seconds:
          type: integer
          format: int64
          description: Total proxy connection time consumed on the day.
        bytes_transferred:
          type: integer
          format: int64
          description: Total bytes transferred to clients.
    WebhookEndpoint:
      type: object
      description: A delivery target for project audit/event notifications.
      required:
        - id
        - project_id
        - url
        - format
        - enabled
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: Unique webhook endpoint identifier (prefixed).
          example: whk_01h455vb4pex5vsknk084sn02q
        project_id:
          type: string
          description: Owning project ID.
        url:
          type: string
          description: HTTPS endpoint that receives event deliveries.
          example: https://example.com/hooks/pgbeam
        format:
          type: string
          enum:
            - json
            - splunk_hec
            - datadog
            - elastic
          description: Payload format for delivered events.
        event_types:
          type: array
          description: Event types to deliver. Empty means all events.
          items:
            type: string
            description: An event type (e.g. blocked, anomaly, approval).
        enabled:
          type: boolean
          description: Whether deliveries are active for this endpoint.
        description:
          type: string
          description: Human-readable label for the endpoint.
        created_at:
          type: string
          format: date-time
          description: When the endpoint was created.
        updated_at:
          type: string
          format: date-time
          description: When the endpoint was last updated.
    WebhookEndpointInput:
      type: object
      description: Mutable fields of a webhook endpoint (used for create and update).
      required:
        - url
      properties:
        url:
          type: string
          minLength: 1
          maxLength: 2048
          description: HTTPS endpoint that receives event deliveries.
          example: https://example.com/hooks/pgbeam
        secret:
          type: string
          maxLength: 256
          writeOnly: true
          description: Shared secret used to sign delivery payloads. Write-only.
        format:
          type: string
          enum:
            - json
            - splunk_hec
            - datadog
            - elastic
          default: json
          description: Payload format for delivered events.
        event_types:
          type: array
          description: Event types to deliver. Empty means all events.
          items:
            type: string
            description: An event type.
        enabled:
          type: boolean
          default: true
          description: Whether deliveries are active for this endpoint.
        description:
          type: string
          maxLength: 256
          description: Human-readable label for the endpoint.
    WebhookTestResponse:
      type: object
      description: Result of sending a synthetic test event to a webhook endpoint.
      required:
        - delivery_id
        - status
      properties:
        delivery_id:
          type: string
          description: Identifier of the test delivery.
        status:
          type: string
          description: Outcome of the test delivery (delivered or failed).
        status_code:
          type: integer
          description: HTTP status code returned by the endpoint, if a response was received.
        error:
          type: string
          description: Error detail when the test delivery failed.
    ListWebhookEndpointsResponse:
      type: object
      description: Cursor-paginated list of webhook endpoints for a project.
      required:
        - webhooks
      properties:
        webhooks:
          type: array
          description: Webhook endpoints on the current page.
          items:
            $ref: '#/components/schemas/WebhookEndpoint'
        next_page_token:
          type: string
          description: Token for the next page. Empty if no more results.
x-iac-resources:
  Project:
    description: Manages a PgBeam project with a primary database.
    operations:
      create: createProject
      read: getProject
      update: updateProject
      delete: deleteProject
      list: listProjects
    connection-details:
      - proxy_host
    extra-outputs:
      primary_database_id:
        path: database.id
        description: ID of the primary database created with this project.
    adoption:
      match-fields:
        - name
      list-query-params:
        org_id: org_id
        page_size: 100
  Database:
    description: Manages an upstream database connection within a PgBeam project.
    operations:
      create: createDatabase
      read: getDatabase
      update: updateDatabase
      delete: deleteDatabase
      list: listDatabases
    connection-details:
      - connection_string
  Replica:
    description: Manages a read replica for a PgBeam database.
    operations:
      create: createReplica
      delete: deleteReplica
      list: listReplicas
  CustomDomain:
    description: Manages a custom domain for a PgBeam project.
    operations:
      create: createCustomDomain
      delete: deleteCustomDomain
      list: listCustomDomains
      verify: verifyCustomDomain
    connection-details:
      - dns_verification_token
  CacheRule:
    description: Manages a per-query cache rule. Deletion disables caching (soft-delete).
    id-field: query_hash
    operations:
      upsert: updateCacheRule
      list: listCacheRules
    soft-delete:
      cache_enabled: false
  SpendLimit:
    description: Manages the monthly spend limit for an organization.
    id-field: org_id
    operations:
      upsert: updateSpendLimit
      read: getOrganizationPlan
    soft-delete:
      spend_limit: null
  AgentCredential:
    description: >-
      Manages a scoped agent credential (a PgBeam-issued Postgres login plus a hosted MCP token) for an AI agent. The
      connection string and MCP token are one-time secrets returned only at creation and exposed as sensitive computed
      outputs; they cannot be retrieved again. To rotate the secrets, taint/replace the resource (or use the rotate
      endpoint out of band).
    operations:
      create: createAgentCredential
      read: getAgentCredential
      update: updateAgentCredentialStatus
      delete: revokeAgentCredential
      list: listAgentCredentials
    extra-outputs:
      connection_string:
        path: connection_string
        description: One-time guarded Postgres connection string for this agent credential (shown once).
        sensitive: true
      mcp_url:
        path: mcp_url
        description: Hosted agent-database MCP endpoint for this project. Use with the mcp_token as a bearer token.
      mcp_token:
        path: mcp_token
        description: One-time bearer token for the hosted MCP endpoint (shown once).
        sensitive: true
    adoption:
      match-fields:
        - name
      list-query-params:
        page_size: 100
  PolicyProfile:
    description: >-
      Manages a policy profile: a named bundle of agent-gateway enforcement rules (access mode, table allow/deny lists,
      statement-kind rules, PII masking rules, per-relation row filters, query/egress budgets, write mode, approvals,
      and migration safety) attached to agent credentials and enforced in the PG wire protocol. Nested-list fields
      (masking_rules, row_filters) and the nested statement_rules object are expressed as structured config.
    operations:
      create: createPolicyProfile
      read: getPolicyProfile
      update: updatePolicyProfile
      delete: deletePolicyProfile
      list: listPolicyProfiles
    adoption:
      match-fields:
        - name
      list-query-params:
        page_size: 100
  WebhookEndpoint:
    description: >-
      Manages a webhook endpoint that receives project audit and anomaly event deliveries. The signing secret is
      write-only and never returned by the API.
    operations:
      create: createWebhookEndpoint
      read: getWebhookEndpoint
      update: updateWebhookEndpoint
      delete: deleteWebhookEndpoint
      list: listWebhookEndpoints
    adoption:
      match-fields:
        - url
      list-query-params:
        page_size: 100
  SelfHostEnrollment:
    description: >-
      Manages a self-host (BYOC) enrollment: a token a self-hosted proxy uses to authenticate to the control plane's
      config/audit stream. The token is a one-time secret returned only at creation and exposed as a sensitive computed
      output; it cannot be retrieved again. To rotate the token, replace the resource. Deletion revokes the enrollment.
    operations:
      create: createSelfHostEnrollment
      delete: revokeSelfHostEnrollment
      list: listSelfHostEnrollments
    extra-outputs:
      token:
        path: token
        description: One-time enrollment token (pbh_...) for the self-hosted proxy's GRPC_AUTH_TOKEN (shown once).
        sensitive: true