Implementation:TobikoData Sqlmesh WebClient OpenAPI Spec

Knowledge Sources	TobikoData_Sqlmesh
Domains	API_Documentation, Web_UI, Web_API
Last Updated	2026-02-07 20:00 GMT

Overview

OpenAPI 3.1 specification defining the SQLMesh web client API contract.

Description

This OpenAPI specification defines the RESTful API exposed by the SQLMesh web server backend for the browser-based UI client. It documents all available endpoints, request/response schemas, and operations that the web client uses to interact with SQLMesh projects, models, plans, and environments.

The spec follows OpenAPI 3.1.0 standard and is generated by FastAPI, providing automatic API documentation, validation, and type safety. Key API operations include:

apply: Apply a SQLMesh plan to update an environment
evaluate: Execute and evaluate models with configurable row limits
Plan generation and preview
Model metadata and lineage queries
Environment management

This specification serves as the contract between the React/TypeScript web client and the Python FastAPI backend, ensuring consistent API behavior and enabling type-safe client code generation.

Usage

This file is used for API documentation, TypeScript client generation, and runtime request/response validation. The web client imports generated types to ensure type safety when making API calls.

Code Reference

Source Location

Repository: TobikoData_Sqlmesh
File: web/client/openapi.json

Signature

{
  "openapi": "3.1.0",
  "info": {
    "title": "FastAPI",
    "version": "0.1.0"
  },
  "paths": {
    "/api/commands/apply": { ... },
    "/api/commands/evaluate": { ... },
    ...
  },
  "components": {
    "schemas": { ... }
  }
}

Import

# Generate TypeScript types for web client
openapi-typescript web/client/openapi.json -o web/client/src/generated/api.ts

# View in browser
# Start web server and navigate to:
# http://localhost:8000/docs (Swagger UI)

I/O Contract

Inputs

Name	Type	Required	Description
FastAPI Server	Python App	Yes	Running SQLMesh web server implementing this spec

Outputs

Name	Type	Description
API Documentation	HTML	Interactive API docs (Swagger UI / ReDoc)
Type Definitions	TypeScript	Generated types for web client
Validation Schema	JSON Schema	Request/response validation rules

Implementation Details

Key Endpoints

POST /api/commands/apply

Purpose: Apply a SQLMesh plan to update an environment
Description: "Apply a plan"
Request Body: JSON with plan configuration (environment, backfill settings, etc.)
Response: 200 OK - PlanApplyStageTracker or null
Error: 422 Unprocessable Entity - Validation errors

POST /api/commands/evaluate

Purpose: Evaluate a model and return results
Description: "Evaluate a model with a default limit of 1000"
Request Body: JSON with model identifier and evaluation parameters
Response: 200 OK - Evaluation results with data preview
Error: 422 Unprocessable Entity - Validation errors

Schema Components

The specification defines reusable schemas in `components/schemas`:

PlanApplyStageTracker: Tracks progress of plan application stages
HTTPValidationError: Standard error format for validation failures
Body_initiate_apply_api_commands_apply_post: Request schema for apply operation
Additional schemas for SQLMesh entities (models, snapshots, environments, intervals)

Response Formats

Success Responses: 200 OK with JSON payload
Validation Errors: 422 Unprocessable Entity with detailed error information
Content Type: application/json for all endpoints

File Characteristics

Size: 2,243 lines
Format: JSON
Generation: Auto-generated by FastAPI from Python type hints and Pydantic models
Version: OpenAPI 3.1.0 (latest OpenAPI specification)

Differences from VSCode OpenAPI

While similar in structure to the VSCode extension's OpenAPI spec, the web client spec may include:

Additional UI-specific endpoints (lineage visualization, metadata queries)
Different authentication/authorization schemas
Web-optimized response formats (pagination, filtering)

Generation Process

The spec is automatically generated from FastAPI route definitions with type annotations:

# In web/server/main.py
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class ApplyRequest(BaseModel):
    environment: str
    plan_id: str
    # ... other fields

@app.post("/api/commands/apply", response_model=PlanApplyStageTracker | None)
async def initiate_apply(request: ApplyRequest) -> PlanApplyStageTracker | None:
    """Apply a plan"""
    ...

# FastAPI auto-generates OpenAPI spec from type hints

Usage Examples

// Generated TypeScript types usage in web client
import type { paths } from '@/generated/api'

type ApplyRequest = paths['/api/commands/apply']['post']['requestBody']['content']['application/json']
type ApplyResponse = paths['/api/commands/apply']['post']['responses']['200']['content']['application/json']

// Type-safe API request
async function applyPlan(request: ApplyRequest): Promise<ApplyResponse> {
  const response = await fetch('/api/commands/apply', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(request),
  })

  if (!response.ok) {
    throw new Error(`Apply failed: ${response.status}`)
  }

  return response.json()
}

// Usage in React component
const { data, error } = useMutation({
  mutationFn: applyPlan,
  onSuccess: (tracker) => {
    console.log('Plan application started:', tracker)
  },
})

# View interactive API documentation
# Start SQLMesh web server
sqlmesh ui

# Navigate to API docs in browser
http://localhost:8000/docs        # Swagger UI
http://localhost:8000/redoc       # ReDoc alternative

# Generate TypeScript client types
cd web/client
npx openapi-typescript openapi.json -o src/generated/api.ts

# Generate full API client (alternative)
npx openapi-generator-cli generate \
  -i openapi.json \
  -g typescript-fetch \
  -o src/generated/client

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment