---
title: "Introspect a connection's schema"
method: GET
path: "/v1/connections/{id}/schema"
tags: ["connections"]
---

# Introspect a connection's schema

`GET /v1/connections/{id}/schema`

## Request

- Base URL: `https://data.thinair.co`
- URL: `https://data.thinair.co/v1/connections/{id}/schema`
- Auth: API key in header `x-api-key`

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.

## Path parameters

- `id` string, required: Connection name or id (see `/v1/connections`).

## Query parameters

- `refresh` union: Set to `true` to bypass the 1-hour cache and force live introspection. Default: `false` (use cache when present).
  - 'true'
  - 'false'

## Response `200`

Schema descriptor.

- ConnectionSchemaResponse: 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.
  - `schema` SchemaResult, required
    - `tables` SchemaTable[], required
      - `name` string, required
      - `columns` SchemaColumn[], required
        - `name` string, required
        - `type` string, required
        - `nullable` boolean, required
        - `isPrimaryKey` boolean
        - `isForeignKey` boolean
        - `referencesTable` string
        - `referencesColumn` string
        - `defaultValue` string
      - `indexes` SchemaIndex[]
        - `name` string, required
        - `columns` string[], required
        - `isUnique` boolean, required
        - `isPrimary` boolean, required
      - `rowCountEstimate` number
    - `dbType` 'postgres' | 'mysql' | 'mssql', required
    - `schema` string: 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` string[]: 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` object[]: Populated only when the introspected schema returned 0 tables. Lists other namespaces with non-zero table counts so clients can suggest a re-introspection.
      - `schema` string, required
      - `tableCount` number, required
  - `meta` ConnectionSchemaMeta, required
    - `executionTimeMs` integer, required
    - `rowCount` integer, required
    - `cacheHit` boolean
    - `connection` string, required
    - `dialect` 'postgres' | 'mysql' | 'mssql', required

## Other responses

- `400`: Invalid query parameter.
- `401`: Authentication required.
- `404`: No connection matches `id` for this tenant.
- `429`: Quota exceeded for this tenant.
- `502`: Upstream introspection failed (origin refused / DNS / TLS).

---

[API](https://skmtc.dev/thinair/apis/thinair-data-api.md) · [All operations](https://skmtc.dev/thinair/apis/thinair-data-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thinair/apis/thinair-data-api/revisions/8a2a2d1b2400?raw)