Foundational Monitors API

openapi: 3.2.0
info:
  title: Foundational Monitors API
  version: 0.1.0
servers:
- url: /api/v1
tags:
- name: Monitors
paths:
  /monitors/preview:
    post:
      tags:
      - Monitors
      summary: Run a monitor once as Foundational's connector
      description: 'Run a draft or saved monitor once with the connector''s warehouse credentials and return what it sees.


        The target is a table (`kind: "table"`) or a custom query (`kind: "custom_query"`, by

        `custom_query_id` or as unsaved `query_text`). Omit `columns` to run the saved monitor''s checks;

        send draft checks to try them before saving.


        The response holds the result columns, up to `sample_rows` rows, the row count the checks saw

        (`rows_returned`) and each check''s value keyed `.`. `rows_returned == 0`, or every

        check listed in `null_metrics`, means the connector sees no data — often a missing privilege or a

        row-access policy rather than an empty table. A warehouse error comes back in `error`, not as a

        failed request. Nothing is stored. Queries run for at most 60 seconds.'
      operationId: preview_monitor_monitors_preview_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitorPreviewRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorPreviewResult'
        '400':
          description: The platform has no monitor queries, or the SQL is not one read-only query
        '404':
          description: The connector or custom query is not in the organization
        '429':
          description: Too many previews
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /monitors/custom-queries:
    put:
      tags:
      - Monitors
      summary: Create or replace a custom-query monitor
      description: 'Save a custom query and its checks in one call; the next scheduled scan runs it.


        Preview it first with `POST /monitors/preview` to see what the connector returns.'
      operationId: upsert_custom_query_monitor_monitors_custom_queries_put
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicCustomQueryMonitorRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicCustomQueryMonitorResponse'
        '400':
          description: The SQL is not one read-only query
        '404':
          description: The connector or custom query is not in the organization
        '409':
          description: A column is not returned by the query, or the monitor is managed by a data contract
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SegmentationConfig:
      properties:
        segment_by:
          items:
            type: string
          type: array
          title: Segment By
          default: []
        max_segments:
          type: integer
          title: Max Segments
          default: 1000
      type: object
      title: SegmentationConfig
      description: Configuration for metric segmentation by column values.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    TablePreviewTarget:
      properties:
        kind:
          type: string
          const: table
          title: Kind
        dbName:
          type: string
          maxLength: 512
          title: Dbname
        schemaName:
          type: string
          maxLength: 512
          title: Schemaname
        tableName:
          type: string
          maxLength: 512
          title: Tablename
        fixedCase:
          type: boolean
          title: Fixedcase
          description: 'The names are quoted identifiers: do not case-fold them.'
          default: false
      type: object
      required:
      - kind
      - dbName
      - schemaName
      - tableName
      title: TablePreviewTarget
      description: A warehouse table, named as a table monitor names it.
    MonitorPreviewResult:
      properties:
        executedAs:
          type: string
          title: Executedas
          description: The connector the queries ran as, and its role or user where known.
        columns:
          items:
            type: string
          type: array
          title: Columns
          default: []
        sampleRows:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Samplerows
          default: []
        sampleQuery:
          anyOf:
          - type: string
          - type: 'null'
          title: Samplequery
        metricsQuery:
          anyOf:
          - type: string
          - type: 'null'
          title: Metricsquery
        checkValues:
          additionalProperties:
            anyOf:
            - type: number
            - type: string
            - type: 'null'
          type: object
          title: Checkvalues
          description: Each check's value, keyed `<column>.<metric>` (plus the segment when segmented).
          default: {}
        rowsReturned:
          anyOf:
          - type: integer
          - type: 'null'
          title: Rowsreturned
          description: Rows of the target the checks saw.
        nullMetrics:
          items:
            type: string
          type: array
          title: Nullmetrics
          description: Checks that came back NULL, named `<column>.<metric>`.
          default: []
        returnedNoData:
          type: boolean
          title: Returnednodata
          description: No rows, or NULL for every check.
          default: false
        durationMs:
          type: integer
          title: Durationms
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: The warehouse's error, when a query failed.
      type: object
      required:
      - executedAs
      - durationMs
      title: MonitorPreviewResult
    PublicCustomQueryMonitorResponse:
      properties:
        customQueryId:
          type: string
          format: uuid
          title: Customqueryid
        connectorId:
          type: string
          format: uuid
          title: Connectorid
        name:
          type: string
          title: Name
        platform:
          type: string
          title: Platform
        columnsNames:
          items:
            type: string
          type: array
          title: Columnsnames
        columns:
          additionalProperties:
            $ref: '#/components/schemas/ColumnMetricsConfig'
          type: object
          title: Columns
        emptyResult:
          anyOf:
          - $ref: '#/components/schemas/EmptyResultPolicy'
          - type: 'null'
      type: object
      required:
      - customQueryId
      - connectorId
      - name
      - platform
      - columnsNames
      - columns
      title: PublicCustomQueryMonitorResponse
    MonitorPreviewRequest:
      properties:
        connectorId:
          type: string
          format: uuid
          title: Connectorid
          description: Public id of the warehouse connector to run as.
        target:
          oneOf:
          - $ref: '#/components/schemas/TablePreviewTarget'
          - $ref: '#/components/schemas/CustomQueryPreviewTarget'
          title: Target
          discriminator:
            propertyName: kind
            mapping:
              custom_query: '#/components/schemas/CustomQueryPreviewTarget'
              table: '#/components/schemas/TablePreviewTarget'
        columns:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/ColumnMetricsConfig'
            type: object
          - type: 'null'
          title: Columns
          description: 'Draft column checks, keyed like a monitor config. Omitted: the saved monitor''s checks. Empty: no checks, only the row count and sample rows.'
        segmentation:
          anyOf:
          - $ref: '#/components/schemas/SegmentationConfig'
          - type: 'null'
        sampleRows:
          type: integer
          maximum: 100.0
          minimum: 0.0
          title: Samplerows
          default: 20
      type: object
      required:
      - connectorId
      - target
      title: MonitorPreviewRequest
    ObservabilityMetricType:
      type: string
      enum:
      - null_count
      - zero_count
      - true_count
      - row_count
      - distinct_values_count
      - min
      - max
      - count
      - sum
      - avg
      - pattern
      - allowed_values
      title: ObservabilityMetricType
    CheckConfig:
      properties:
        min_threshold:
          anyOf:
          - type: number
          - type: 'null'
          title: Min Threshold
        max_threshold:
          anyOf:
          - type: number
          - type: 'null'
          title: Max Threshold
        pattern:
          anyOf:
          - type: string
          - type: 'null'
          title: Pattern
        allowed_values:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Allowed Values
      type: object
      title: CheckConfig
    CustomQueryPreviewTarget:
      properties:
        kind:
          type: string
          const: custom_query
          title: Kind
        customQueryId:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Customqueryid
        queryText:
          anyOf:
          - type: string
            maxLength: 100000
          - type: 'null'
          title: Querytext
        targetDbName:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
          title: Targetdbname
          description: Database the SQL's unqualified names resolve in.
        targetSchemaName:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
          title: Targetschemaname
          description: Schema the SQL's unqualified names resolve in.
      type: object
      required:
      - kind
      title: CustomQueryPreviewTarget
      description: 'A custom-query monitor: a saved custom query by id, or SQL that is not saved yet.'
    ColumnMetricsConfig:
      properties:
        column_name:
          type: string
          title: Column Name
        metrics:
          additionalProperties:
            $ref: '#/components/schemas/CheckConfig'
          propertyNames:
            $ref: '#/components/schemas/ObservabilityMetricType'
          type: object
          title: Metrics
          default: {}
        fixed_case:
          type: boolean
          title: Fixed Case
          default: false
      type: object
      required:
      - column_name
      title: ColumnMetricsConfig
    EmptyResultPolicy:
      type: string
      enum:
      - pass
      - alert
      title: EmptyResultPolicy
      description: What a monitor run that returns no rows, or NULL for every check, means to the customer.
    PublicCustomQueryMonitorRequest:
      properties:
        customQueryId:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Customqueryid
          description: 'The monitor to replace. Omitted: create one.'
        connectorId:
          type: string
          format: uuid
          title: Connectorid
          description: Public id of the warehouse connector the query runs on.
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
          default: ''
        query:
          type: string
          title: Query
          description: One read-only SQL query.
        enabled:
          type: boolean
          title: Enabled
          default: true
        columnsNames:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Columnsnames
          description: 'Result columns the monitor exposes. Omitted: every column the query returns.'
        columns:
          additionalProperties:
            $ref: '#/components/schemas/ColumnMetricsConfig'
          type: object
          title: Columns
          description: 'Checks per column, keyed by any stable id. Empty: the query has no checks.'
          default: {}
        emptyResult:
          anyOf:
          - $ref: '#/components/schemas/EmptyResultPolicy'
          - type: 'null'
          description: 'Whether a run with no rows, or NULL for every check, is healthy (`pass`) or alerts (`alert`). Omitted on an update: the monitor keeps its setting.'
      type: object
      required:
      - connectorId
      - name
      - query
      title: PublicCustomQueryMonitorRequest