thinair-co Migrations API

openapi: 3.2.0
info:
  title: ThinAir Data Migrations 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: Migrations
paths:
  /v1/migrations/generate:
    post:
      summary: Generate a SQL migration script from a free-text intent
      description: Parse a plain-English migration intent (e.g. 'add index on positions(deviceid, fixtime desc)') and emit dialect-correct up + down SQL plus warnings. Never executes — output is for the caller to review and run manually. Costs 1 quota unit per call. Build tier (or higher) required.
      tags:
      - Migrations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MigrationsGenerateRequest'
            example:
              intent: add nullable notes column to vehicles
      responses:
        '200':
          description: Generated migration. Always review `data.warnings[]` before running — some operations (drop column, create unique index) are destructive or fail when constraints aren't met.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MigrationsGenerateResponse'
        '400':
          description: Invalid request body.
          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: Tier gate — requires Build plan or higher (caller is on Discover).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Connection not found, or the tenant has no connections registered.
          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 database unreachable during schema introspection — no quota debited.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: postV1MigrationsGenerate
      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).
    MigrationsGenerateRequest:
      type: object
      properties:
        connection:
          type: string
          minLength: 1
          maxLength: 256
          description: Connection name (display) or id (uuid). When omitted, the tenant's default (first added) connection is used. Same fallback as the MCP `generate_migration` tool.
          example: fleet
        intent:
          type: string
          minLength: 1
          maxLength: 2000
          description: 'Plain-English description of the migration. Examples: ''add soft delete to drivers'', ''add index on trips(driver_id, created_at)'', ''rename email to email_address on drivers''. Phrasing matters: name the table, the column, and the action explicitly — the intent parser extracts those three and will reject a request it cannot resolve rather than guess.'
          example: add nullable notes column to vehicles
        target_dialect:
          type: string
          enum:
          - postgres
          - mysql
          - mssql
          description: Optional target dialect. The handler currently derives dialect from the resolved connection — this hint is informational only and reserved for future cross-dialect translation. Mismatches between hint and resolved dialect surface in response meta but don't override.
        dry_run:
          type: boolean
          description: Reserved for future support. The current handler NEVER executes the generated SQL — it only emits up + down strings — so dry_run is effectively always true. Echoed in response meta when set.
      required:
      - intent
      description: Generate a SQL migration script (up + down + warnings) from a free-text intent. Costs 1 quota unit. Build tier (or higher) required.
    MigrationsGenerateResponse:
      type: object
      properties:
        data:
          type: object
          additionalProperties: {}
        display:
          type: object
          additionalProperties: {}
        summary:
          type: string
        insights:
          type: array
          items:
            type: object
            additionalProperties: {}
        meta:
          type: object
          additionalProperties: {}
      required:
      - data
      - display
      - meta
      description: Generated migration. `data.up_sql` runs the change, `data.down_sql` rolls it back, `data.warnings[]` flags caveats (PG `CONCURRENTLY` outside a tx, NULL backfill required, irreversible drops, …). Mirrors the MCP `generate_migration` tool output. Some intents emit `-- TODO:` skeletons + a parser-couldn't-resolve warning when the phrasing isn't recognized.
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key