Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
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