thinair-co Tables API

openapi: 3.2.0
info:
  title: ThinAir Data Tables API
  version: 1.0.0
  description: Connection management, schema introspection, and SQL query execution against tenant-owned databases. Both interfaces (REST and MCP) consume the same service layer; this spec describes only the REST surface.
servers:
- url: https://data.thinair.co
security:
- apiKeyHeader: []
tags:
- name: Tables
paths:
  /v1/tables/{t}/profile:
    get:
      summary: Profile a table
      description: 'Return per-column distributions, null rates, cardinality, basic numeric / date stats, and PII classification for one table. Requires the Build plan or higher. Quota: 1 capability unit.'
      tags:
      - Tables
      parameters:
      - schema:
          type: string
          minLength: 1
          maxLength: 256
          description: Table name. Accepts `table`, `schema.table`, or `database.schema.table` forms — same wire shape the MCP `data_profile` tool accepts. Use `?connection=` to override the tenant's default connection rather than prefixing the path.
          example: public.vehicles
        required: true
        name: t
        in: path
      - schema:
          type: string
          minLength: 1
          maxLength: 256
          description: Connection name (display) or id (uuid). Resolved via name match first, then id match. Call /v1/connections to list available names.
          example: fleet
        required: false
        name: connection
        in: query
      - schema:
          type: integer
          minimum: 100
          maximum: 1000000
          description: Advisory upper bound on rows to scan. Today the underlying profiler decides sampling internally based on table size; the value is reserved for the post-migration profile micro-spec.
          example: 50000
        required: false
        name: sample_rows
        in: query
      - schema:
          type: string
          minLength: 1
          description: Comma-separated column allowlist. Today the profiler covers the first 50 columns; the value is reserved for the post-migration profile micro-spec.
          example: make,model,year
        required: false
        name: columns
        in: query
      responses:
        '200':
          description: Profile result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TablesProfileResponse'
        '400':
          description: Invalid table name or query parameters.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Authentication required or failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: The current plan does not include data_profile.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Connection not found, no connections configured, or table missing from the connection's schema.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Quota exceeded.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: getV1TablesByTProfile
      x-operation-id-source: derived
  /v1/tables/{t}/anomalies:
    get:
      summary: Detect anomalies in a table
      description: 'Scan a table for unusual patterns: volume drops/spikes, data gaps, value concentration, high null rates, stale data. Severity-ranked. Tables > 100k rows use a sampled path (~5%) — alerts may carry `sampled: true`. Quota: 1 capability unit.'
      tags:
      - Tables
      parameters:
      - schema:
          type: string
          minLength: 1
          maxLength: 256
          description: Table name. Accepts `table`, `schema.table`, or `database.schema.table` forms — same wire shape the MCP `detect_anomalies` tool accepts. Use `?connection=` to override the tenant's default connection.
          example: public.telemetry_events
        required: true
        name: t
        in: path
      - schema:
          type: string
          minLength: 1
          maxLength: 256
          description: Connection name (display) or id (uuid). Resolved via name match first, then id match. Call /v1/connections to list available names.
          example: fleet
        required: false
        name: connection
        in: query
      - schema:
          type: string
          minLength: 1
          maxLength: 128
          description: Column to focus the scan on. Today maps to the date-trend column for volume / staleness anomalies; the post-migration spec broadens it to a per-column allowlist.
          example: created_at
        required: false
        name: column
        in: query
      - schema:
          type: string
          format: date-time
          description: ISO-8601 cutoff. Anomalies older than this are excluded. Today the underlying scan uses a fixed 14-day window; the value is reserved for the migrated implementation.
          example: '2026-04-01T00:00:00Z'
        required: false
        name: since_iso
        in: query
      - schema:
          type: string
          enum:
          - low
          - medium
          - high
          description: Minimum severity to include. `low` returns everything; `medium` drops `low`; `high` drops `low` and `medium`.
          example: medium
        required: false
        name: severity
        in: query
      responses:
        '200':
          description: Anomaly scan result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TablesAnomaliesResponse'
        '400':
          description: Invalid table name or query parameters.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Authentication required or failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Connection not found, no connections configured, or table missing from the connection's schema.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Quota exceeded.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: getV1TablesByTAnomalies
      x-operation-id-source: derived
components:
  schemas:
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        code:
          type: string
          description: Stable internal_code; see /docs/errors
        request_id:
          type: string
        instance:
          type: string
        retry_after_ms:
          type: integer
        upgrade_url:
          type:
          - string
          - 'null'
          format: uri
          description: Present on QUOTA_EXCEEDED (429) and TRIAL_EXPIRED (401). Where it points depends on the caller's tenant. For a tenant with no active subscription (Discover, Developer Trial, or a cancelled subscription) it is a checkout link preselecting the caller's next plan tier, tagged with `src` for the upgrade-prompt funnel. For a tenant that already has an active subscription it is the console Billing view (https://data.thinair.co/developers#billing), where the plan is changed through the Billing portal; no checkout link is issued, because a second checkout would open a second subscription. `null`/absent once there is no self-serve tier above the caller's plan.
        expired_at:
          type:
          - string
          - 'null'
          format: date-time
          description: 'TRIAL_EXPIRED only: ISO timestamp the Developer Trial key expired.'
        plan:
          type: string
          description: 'TRIAL_EXPIRED only: the plan the expired key was on (normally `dev_trial`).'
        quota:
          anyOf:
          - type: integer
          - type: string
            enum:
            - unlimited
          description: 'TRIAL_EXPIRED only: the daily query limit the expired plan carried.'
      required:
      - type
      - title
      - status
      - detail
      - code
      - request_id
      - instance
      description: RFC 7807 problem-details with ThinAir extensions (code, request_id, retry_after_ms, upgrade_url, and — TRIAL_EXPIRED only — expired_at/plan/quota).
    TablesProfileResponse:
      type: object
      properties:
        profiles:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              type:
                type: string
              nullable:
                type: boolean
              isPrimaryKey:
                type: boolean
              null_pct:
                type: number
              cardinality:
                type: number
              min:
                anyOf:
                - type: number
                - type: string
              max:
                anyOf:
                - type: number
                - type: string
              avg:
                type: number
              earliest:
                type: string
              latest:
                type: string
              pii_risk:
                type: boolean
              pii_type:
                type: string
            required:
            - name
        summary:
          type: string
        insights:
          type: array
          items:
            type: object
            properties:
              severity:
                type: string
              message:
                type: string
              column:
                type: string
              value: {}
            required:
            - severity
            - message
        meta:
          type: object
          properties:
            executionTimeMs:
              type: number
            rowCount:
              type: number
            connection:
              type: string
            dialect:
              type: string
              enum:
              - postgres
              - mysql
              - mssql
          required:
          - executionTimeMs
          - rowCount
          - connection
          - dialect
      required:
      - profiles
      - meta
      description: Per-column profile + health insights for one table. Mirrors the MCP `data_profile` envelope shape.
    TablesAnomaliesResponse:
      type: object
      properties:
        alerts:
          type: array
          items:
            type: object
            properties:
              severity:
                type: string
              type:
                type: string
              column:
                type:
                - string
                - 'null'
              message:
                type: string
              recommendation:
                type: string
              value: {}
            required:
            - severity
        summary:
          type: string
        insights:
          type: array
          items:
            type: object
            properties:
              severity:
                type: string
              message:
                type: string
              column:
                type: string
              value: {}
            required:
            - severity
            - message
        meta:
          type: object
          properties:
            executionTimeMs:
              type: number
            connection:
              type: string
            dialect:
              type: string
              enum:
              - postgres
              - mysql
              - mssql
          required:
          - executionTimeMs
          - connection
          - dialect
      required:
      - alerts
      - meta
      description: Severity-ranked anomaly alerts for one table. Mirrors the MCP `detect_anomalies` envelope shape.
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key