thinair-co Billing API

openapi: 3.2.0
info:
  title: ThinAir Data Billing 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: Billing
paths:
  /v1/quota:
    get:
      summary: Get caller's current quota state
      description: Returns the caller's plan, daily usage, remaining queries, monthly limit, and upgrade options. **Free to call** — never debits quota and never returns 429 (a quota-exhausted user must still be able to discover their state).
      tags:
      - Billing
      responses:
        '200':
          description: Caller's quota snapshot.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaResponse'
        '401':
          description: Authentication required or failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: getV1Quota
      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).
    QuotaResponse:
      type: object
      properties:
        schema_version:
          type: string
          enum:
          - v1
        mcp:
          type: object
          properties:
            plan:
              type: string
              example: discover
            used_today:
              type: integer
              minimum: 0
            daily_limit:
              anyOf:
              - type: integer
                minimum: 0
              - type: string
                enum:
                - unlimited
            remaining_today:
              anyOf:
              - type: integer
                minimum: 0
              - type: string
                enum:
                - unlimited
            monthly_limit:
              anyOf:
              - type: integer
                minimum: 0
              - type: string
                enum:
                - unlimited
            price_per_month:
              type: string
              example: $0
            suggested_upgrade:
              type:
              - string
              - 'null'
            upgrade_url:
              type:
              - string
              - 'null'
            reset_at:
              type: string
              example: 00:00 UTC daily
          required:
          - plan
          - used_today
          - daily_limit
          - remaining_today
          - monthly_limit
          - price_per_month
          - suggested_upgrade
          - upgrade_url
          - reset_at
      required:
      - schema_version
      - mcp
      description: 'Caller''s current quota state — plan, daily usage, remaining queries, monthly limit, and upgrade options. Mirrors geo-mcp''s /v1/quota response shape so cross-product clients can share a parser. Plan-name divergence: data-mcp uses discover|build|architect|enterprise (vs geo''s free|starter|pro|enterprise|admin) — treat `plan` as an opaque string.'
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key