thinair-co Connections API

openapi: 3.2.0
info:
  title: ThinAir Data Connections 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: Connections
paths:
  /v1/connections:
    get:
      summary: List the tenant's database connections
      description: Returns name, id, dialect, and created-at for every connection registered to the calling tenant. Use the `name` field as the path parameter for `/v1/connections/:id/health` and `/v1/connections/:id/schema`. **Free to call** — never debits quota.
      tags:
      - Connections
      responses:
        '200':
          description: Connection inventory.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionsListResponse'
        '401':
          description: Authentication required or the session has no tenant binding.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: getV1Connections
      x-operation-id-source: derived
  /v1/connections/{id}/health:
    get:
      summary: Probe a connection's health
      description: Run a dialect-appropriate `SELECT 1` ping and best-effort version probe against the connection identified by `id` (name match first, id match second). Returns latency, server version, current database, and current schema. Costs 1 quota unit per call.
      tags:
      - Connections
      parameters:
      - schema:
          type: string
          description: Connection name or id (see `/v1/connections`).
          example: fleet
        required: true
        name: id
        in: path
      responses:
        '200':
          description: 'Probe completed (the connection may have reported `ok: false` for an auth or origin failure — still a 200; the body''s `ok` is the success signal).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionHealthResponse'
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: No connection matches `id` for this tenant.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Quota exceeded for this tenant.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '502':
          description: Connection unreachable (origin refused / DNS / TLS / etc).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '504':
          description: Connection probe timed out.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: getV1ConnectionsByIdHealth
      x-operation-id-source: derived
  /v1/connections/{id}/schema:
    get:
      summary: Introspect a connection's schema
      description: 'Returns tables, columns, primary keys, and indexes (MySQL: indexes not reported yet; foreign keys are not reported) for the connection identified by `id` (name match first, id match second). Results are cached 1 hour; pass `refresh=true` to bypass the cache and force live introspection. Costs 1 quota unit per call.'
      tags:
      - Connections
      parameters:
      - schema:
          type: string
          description: Connection name or id (see `/v1/connections`).
          example: fleet
        required: true
        name: id
        in: path
      - schema:
          anyOf:
          - type: string
            enum:
            - 'true'
          - type: string
            enum:
            - 'false'
          description: 'Set to `true` to bypass the 1-hour cache and force live introspection. Default: `false` (use cache when present).'
          example: 'false'
        required: false
        name: refresh
        in: query
      responses:
        '200':
          description: Schema descriptor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionSchemaResponse'
        '400':
          description: Invalid query parameter.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: No connection matches `id` for this tenant.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Quota exceeded for this tenant.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '502':
          description: Upstream introspection failed (origin refused / DNS / TLS).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: getV1ConnectionsByIdSchema
      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).
    ConnectionSchemaResponse:
      type: object
      properties:
        schema:
          $ref: '#/components/schemas/SchemaResult'
        meta:
          $ref: '#/components/schemas/ConnectionSchemaMeta'
      required:
      - schema
      - meta
      description: 'Full schema introspection for one connection — tables, columns, primary keys, and indexes (MySQL connections do not report indexes yet; foreign keys are not reported). `cacheHit: true` when served from the 1-hour cache (sub-30ms). Costs 1 quota unit per call.'
    ConnectionsListResponse:
      type: object
      properties:
        connections:
          type: array
          items:
            $ref: '#/components/schemas/ConnectionRow'
        rowCount:
          type: integer
          minimum: 0
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/ConnectionDuplicateWarning'
      required:
      - connections
      - rowCount
      description: 'Inventory of the tenant''s registered database connections. Rows include name, id, dialect, and created-at. Connection strings and encrypted material are never returned. Free to call (`X-Quota-Cost: 0`).'
    ConnectionDuplicateWarning:
      type: object
      properties:
        code:
          type: string
          enum:
          - DUPLICATE_NAME
        name:
          type: string
        count:
          type: integer
          minimum: 2
        message:
          type: string
      required:
      - code
      - name
      - count
      - message
    ConnectionSchemaMeta:
      type: object
      properties:
        executionTimeMs:
          type: integer
          minimum: 0
        rowCount:
          type: integer
          minimum: 0
        cacheHit:
          type: boolean
        connection:
          type: string
        dialect:
          type: string
          enum:
          - postgres
          - mysql
          - mssql
      required:
      - executionTimeMs
      - rowCount
      - connection
      - dialect
    SchemaTable:
      type: object
      properties:
        name:
          type: string
        columns:
          type: array
          items:
            $ref: '#/components/schemas/SchemaColumn'
        indexes:
          type: array
          items:
            $ref: '#/components/schemas/SchemaIndex'
        rowCountEstimate:
          type: number
      required:
      - name
      - columns
    SchemaIndex:
      type: object
      properties:
        name:
          type: string
        columns:
          type: array
          items:
            type: string
        isUnique:
          type: boolean
        isPrimary:
          type: boolean
      required:
      - name
      - columns
      - isUnique
      - isPrimary
    ConnectionRow:
      type: object
      properties:
        name:
          type: string
          description: Display name. Use this with `/v1/connections/:id/...` (the path id is the connection name).
          example: fleet
        id:
          type: string
          description: Stable internal id. Useful for disambiguating duplicate-name connections; otherwise prefer `name`.
          example: conn_8f2a91c0
        dbType:
          type: string
          enum:
          - postgres
          - mysql
          - mssql
          description: Dialect. Drives SQL syntax choice in subsequent calls.
        createdAt:
          type: string
          description: ISO 8601 timestamp the connection was registered.
      required:
      - name
      - id
      - dbType
      - createdAt
    SchemaResult:
      type: object
      properties:
        tables:
          type: array
          items:
            $ref: '#/components/schemas/SchemaTable'
        dbType:
          type: string
          enum:
          - postgres
          - mysql
          - mssql
        schema:
          type: string
          description: 'The namespace that was introspected. Postgres: the search_path schema (e.g. "public"). MySQL: the database, which IS the schema there. SQL Server: present only when introspection was scoped to one schema. Absent when the connection named no database, or when every schema was swept — in which case naming one would overstate what was covered.'
        notEvaluated:
          type: array
          items:
            type: string
          description: Catalog queries that failed, so their annotations are MISSING rather than absent — e.g. ["primary_keys"] means no table in this response can be assumed to lack a primary key. Omitted when everything was evaluated.
        availableSchemas:
          type: array
          items:
            type: object
            properties:
              schema:
                type: string
              tableCount:
                type: number
            required:
            - schema
            - tableCount
          description: Populated only when the introspected schema returned 0 tables. Lists other namespaces with non-zero table counts so clients can suggest a re-introspection.
      required:
      - tables
      - dbType
    SchemaColumn:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
        nullable:
          type: boolean
        isPrimaryKey:
          type: boolean
        isForeignKey:
          type: boolean
        referencesTable:
          type: string
        referencesColumn:
          type: string
        defaultValue:
          type: string
      required:
      - name
      - type
      - nullable
    ConnectionHealthResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: True when the ping succeeded.
        db_type:
          type: string
          enum:
          - postgres
          - mysql
          - mssql
        version:
          type: string
          example: PostgreSQL 16.2 on x86_64-pc-linux-gnu
        current_database:
          type:
          - string
          - 'null'
        current_schema:
          type:
          - string
          - 'null'
        ping_ms:
          type: integer
          minimum: 0
          description: Wall time of the `SELECT 1` ping in milliseconds.
        total_ms:
          type: integer
          minimum: 0
          description: Wall time of the full probe (ping + version + schema lookup).
        connection:
          type: string
          description: Resolved connection name (matches the row in `/v1/connections`).
      required:
      - ok
      - db_type
      - version
      - current_database
      - current_schema
      - ping_ms
      - total_ms
      - connection
      description: Health-probe result for a single connection. Surfaces dialect, server version, current database/schema, and ping/total latency. Costs 1 quota unit per call.
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key