thinair-co Connections API
The connections API from thinair-co — 3 operation(s) for connections.
The connections API from thinair-co — 3 operation(s) for connections.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/thinair-co:thinair-co-connections-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a 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.
A second provider on the same verified email joins the account you already have.
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