> ## Documentation Index
> Fetch the complete documentation index at: https://developers.zite.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get SQL Schema
> Describe a database's tables, fields, and link tables for composing SQL queries.
Returns the database schema — tables, their fields, and the link tables that connect them — using human-readable names. Use this to discover the exact table and field names to reference from [Run SQL](/api/sql/run-sql).
Names in the response match the human-readable names used in your SQL queries and the Zite SDK.
## Query parameters
| Parameter | Type | Description |
| --------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tables` | string\[] | Optional whitelist of table names to include. Repeat the parameter for multiple tables (e.g. `?tables=Orders&tables=Customers`) or pass a single comma-separated string. Omit to return all tables. |
| `includeFields` | boolean | Whether to include field-level detail. Defaults to `true`. Set to `false` for a cheap overview of just table names. |
## Link tables
`linkTables` describes the junction tables that connect two tables for many-to-many relationships. Each entry exposes the source and target tables along with the columns to join on, so you can traverse linked records in SQL.
## OpenAPI
````yaml api/openapi.json GET /bases/{databaseId}/sql/schema
openapi: 3.0.1
info:
title: Zite DB REST API
description: >-
A REST API for managing Zite databases, tables, fields, and records. Build
database-driven applications with programmatic access to your structured
data.
## What is REST API
A **REST API** simplifies interaction with your database data, allowing for
automation and integration. Following RESTful principles, it seamlessly
connects to retrieve, create, and modify database data.
## Getting Started
### Authentication
All API requests require authentication using your Zite API key in the
Authorization header:
```
Authorization: Bearer YOUR_API_KEY
```
### Base URL
https://tables.zite.com/api/v1
### Rate Limits
API requests are rate limited to ensure service quality. Standard rate
limits apply to all endpoints.
### Error Handling
The API returns standard HTTP status codes and JSON error responses with
detailed error messages.
version: 1.0.0
servers:
- url: https://tables.zite.com/api/v1
description: Zite DB API
security:
- bearerAuth: []
tags:
- name: Databases
description: Operations for managing databases
- name: Tables
description: Operations for managing tables within databases
- name: Fields
description: Operations for managing fields within tables
- name: Records
description: Operations for managing records within tables
- name: Webhooks
description: >-
Operations for managing webhook subscriptions to receive real-time
notifications when database events occur
- name: SQL
description: Run read-only SQL queries against a database and inspect its SQL schema
paths:
/bases/{databaseId}/sql/schema:
get:
tags:
- SQL
summary: Get SQL schema
description: >-
Returns the database schema (tables, fields, and link tables) using
human-readable names, for composing SQL queries.
operationId: getSqlSchema
parameters:
- name: databaseId
in: path
required: true
schema:
type: string
description: The unique identifier of the database
- name: tables
in: query
required: false
schema:
type: array
items:
type: string
style: form
explode: true
description: >-
Optional whitelist of table names to include. Repeat the parameter
for multiple tables (or pass a single comma-separated string). Omit
to return all tables.
- name: includeFields
in: query
required: false
schema:
type: boolean
default: true
description: >-
Whether to include field-level detail for each table. Set to false
for a cheap overview of just table names.
responses:
'200':
description: Database schema
content:
application/json:
schema:
$ref: '#/components/schemas/SqlSchemaResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
SqlSchemaResponse:
type: object
properties:
tables:
type: array
items:
$ref: '#/components/schemas/SqlSchemaTable'
description: The tables in the database.
linkTables:
type: array
items:
$ref: '#/components/schemas/SqlSchemaLinkTable'
description: >-
The junction tables linking tables together for many-to-many
relationships.
required:
- tables
- linkTables
SqlSchemaTable:
type: object
properties:
name:
type: string
description: Human-readable table name.
primaryFieldName:
type: string
description: The name of the table's primary field.
fields:
type: array
items:
$ref: '#/components/schemas/SqlSchemaField'
description: The fields in the table. Omitted when `includeFields=false`.
required:
- name
SqlSchemaLinkTable:
type: object
description: >-
A junction table representing a many-to-many link between two tables.
Join on it to traverse linked records in SQL.
properties:
name:
type: string
description: Name of the link (junction) table.
joins:
type: array
minItems: 2
maxItems: 2
items:
type: string
description: >-
A two-element tuple of [sourceIdColumn, targetIdColumn] used to join
the source and target tables through this link table.
sourceTable:
type: string
description: Name of the source table.
targetTable:
type: string
description: Name of the target table.
sourceTableIdColumn:
type: string
description: Column on the link table referencing the source table's id.
targetTableIdColumn:
type: string
description: Column on the link table referencing the target table's id.
required:
- name
- joins
- sourceTable
- targetTable
- sourceTableIdColumn
- targetTableIdColumn
ErrorResponse:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: Error code
message:
type: string
description: Human-readable error message
required:
- code
- message
required:
- error
SqlSchemaField:
type: object
properties:
name:
type: string
description: Human-readable field name.
type:
type: string
description: The Zite field type (e.g. `single_line_text`, `number`).
postgresType:
type: string
description: The underlying PostgreSQL column type.
linksTo:
type: string
description: For linked-record fields, the name of the table this field links to.
options:
type: array
description: For select fields, the available options as value/label pairs.
items:
type: object
properties:
value:
type: string
label:
type: string
required:
- value
- label
required:
- name
- type
- postgresType
responses:
BadRequest:
description: Invalid request data or validation failure
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidRecordId:
value:
error:
code: INVALID_RECORD_ID
message: Record ID is not in valid UUID format
validationError:
value:
error:
code: BAD_REQUEST
message: Invalid request data or validation failure
Unauthorized:
description: Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: UNAUTHORIZED
message: Invalid or missing API key
NotFound:
description: Requested resource does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: NOT_FOUND
message: Requested resource does not exist
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'Enter your Zite API key. Format: Bearer '
````