Principle:TobikoData Sqlmesh Web Server API

Knowledge Sources	SQLMesh SQLMesh Docs
Domains	Web_Development, Data_Engineering, API_Design
Last Updated	2026-02-07 00:00 GMT

Overview

The Web Server API principle defines the RESTful HTTP interface and real-time event streaming layer that exposes SQLMesh operations to the Web UI client, enabling browser-based project management, plan execution, lineage computation, and data inspection through structured API endpoints.

Description

SQLMesh includes a FastAPI-based web server that serves as the backend for the Web UI. This server exposes the full range of SQLMesh operations through well-defined REST API endpoints organized by domain: commands (apply, evaluate, render, test), files (CRUD operations on project files), directories (create, rename, delete), environments (list, create, delete), models (metadata and information retrieval), lineage (model and column-level dependency computation), plan (initiate, cancel, track), table diff (cross-environment comparison), modules (feature flags), meta (server metadata and version information), and events (Server-Sent Events for real-time console output).

The API follows a resource-oriented design where each endpoint group handles a specific domain. Request validation is handled through Pydantic models that enforce type safety and provide automatic OpenAPI schema generation. The server maintains a SQLMesh Context instance that is shared across requests, providing access to the full SQLMesh engine for model parsing, plan generation, and execution.

Real-time communication between server and client is achieved through Server-Sent Events (SSE), which push console output, plan progress, and file change notifications to the browser without polling. The server also includes a file watcher that monitors project directory changes and broadcasts updates.

The API is specified via OpenAPI 3.1.0, with generated specifications consumed by both the web client (for type-safe API hooks via Orval) and the VSCode extension.

Usage

The Web Server API is used whenever the SQLMesh Web UI is active. It is started via `sqlmesh ui` and provides the communication bridge between the browser-based frontend and the SQLMesh engine running on the user's machine or server. It is essential for teams that use the graphical interface for plan review, lineage exploration, and collaborative model development.

Theoretical Basis

The Web Server API follows these architectural patterns:

Endpoint Organization:

1. Resource-grouped endpoints: `/api/commands`, `/api/files`, `/api/environments`, etc.
2. Each endpoint module handles a single domain with clear separation of concerns
3. Request/response models defined via Pydantic for automatic validation and documentation
4. OpenAPI specification auto-generated from FastAPI route definitions

Communication Patterns:

1. Synchronous REST for request-response operations (file CRUD, model metadata)
2. Server-Sent Events (SSE) for real-time streaming (console output, plan progress)
3. Async execution for long-running operations (plan apply, model evaluation)
4. Error handling with structured error responses containing status codes and messages

State Management:

1. Shared SQLMesh Context maintained across requests
2. File watcher for detecting project changes and broadcasting to connected clients
3. Server-side console implementation that captures output for SSE forwarding
4. Pydantic model layer for serializing SQLMesh internal objects to JSON responses

Security and Configuration:

1. CORS configuration for local development
2. Static file serving for the bundled Web UI client
3. Configurable host and port binding
4. Health check and metadata endpoints for monitoring

Related Pages

Implemented By

• Implementation:TobikoData_Sqlmesh_API_Commands
• Implementation:TobikoData_Sqlmesh_API_Directories
• Implementation:TobikoData_Sqlmesh_API_Environments
• Implementation:TobikoData_Sqlmesh_API_Events
• Implementation:TobikoData_Sqlmesh_API_Files
• Implementation:TobikoData_Sqlmesh_API_Lineage
• Implementation:TobikoData_Sqlmesh_API_Meta
• Implementation:TobikoData_Sqlmesh_API_Models
• Implementation:TobikoData_Sqlmesh_API_Modules
• Implementation:TobikoData_Sqlmesh_API_Plan
• Implementation:TobikoData_Sqlmesh_API_Table_Diff
• Implementation:TobikoData_Sqlmesh_Web_Server_Console
• Implementation:TobikoData_Sqlmesh_Web_Server_Models