SchemaLens API Quick Start

🎮 Try the API Playground

Want to see the API response before writing code? Paste two schemas and click send — no API key required.

💻 Generate API Client Code

Paste your schemas and get copy-paste client code in curl, JavaScript, Python, Go, Rust, Ruby, PHP, Node.js, and TypeScript.

✅ API Status

Check real-time health and latency for every public endpoint before you wire it into production CI/CD.

🎯 What You Can Build

🔑 Step 1 — Get a Pro License Key

🚀 Step 2 — Make Your First Request

The API has one primary endpoint. Send two SQL schemas and receive a full diff, migration SQL, breaking change analysis, and risk score.

Choose your language

curl -L -X POST https://schemalens.tech/api/diff \
  -H "Content-Type: application/json" \
  -H "X-License-Key: SL-XXXX-XXXX-XXXX-XXXX" \
  -d '{
    "schemaA": "CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(255));",
    "schemaB": "CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(255), email VARCHAR(255));",
    "dialect": "postgres",
    "format": "json"
  }'Copy

const response = await fetch('https://schemalens.tech/api/diff', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-License-Key': 'SL-XXXX-XXXX-XXXX-XXXX'
  },
  body: JSON.stringify({
    schemaA: 'CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(255));',
    schemaB: 'CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(255), email VARCHAR(255));',
    dialect: 'postgres',
    format: 'json'
  })
});

const data = await response.json();
console.log(data.migration);
// ALTER TABLE "users" ADD "email" VARCHAR ( 255 );Copy

import requests

response = requests.post(
    'https://schemalens.tech/api/diff',
    headers={
        'Content-Type': 'application/json',
        'X-License-Key': 'SL-XXXX-XXXX-XXXX-XXXX'
    },
    json={
        'schemaA': 'CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(255));',
        'schemaB': 'CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(255), email VARCHAR(255));',
        'dialect': 'postgres',
        'format': 'json'
    }
)

data = response.json()
print(data['migration'])
# ALTER TABLE "users" ADD "email" VARCHAR ( 255 );Copy

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

type DiffRequest struct {
    SchemaA  string `json:"schemaA"`
    SchemaB  string `json:"schemaB"`
    Dialect  string `json:"dialect"`
    Format   string `json:"format"`
}

func main() {
    payload := DiffRequest{
        SchemaA: "CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(255));",
        SchemaB: "CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(255), email VARCHAR(255));",
        Dialect: "postgres",
        Format:  "json",
    }
    body, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", "https://schemalens.tech/api/diff", bytes.NewBuffer(body))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-License-Key", "SL-XXXX-XXXX-XXXX-XXXX")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result["migration"])
}Copy

🆓 Free Diff API — No License Key Required

Perfect for CI/CD pipelines, open-source projects, and quick checks. Returns the full semantic diff, generated migration SQL, and rollback SQL — no license key required.

curl -L -X POST https://schemalens.tech/api/free-diff \
  -H "Content-Type: application/json" \
  -d '{
    "schemaA": "CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(255));",
    "schemaB": "CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(255), email VARCHAR(255));",
    "dialect": "postgres",
    "format": "json"
  }'Copy

Free tier limits: 15 requests/minute. Response includes summary, risk score, all breaking changes, full migration SQL, and rollback SQL. Upgrade to Team for drift alerts, shared workspace, and 30 requests/minute.

📄 See Dedicated curl Demo Page →

🚨 Schema Drift Webhook — Free Alerts

Send diff results from CI/CD to the SchemaLens hosted webhook. It computes the diff, generates a shareable alert page, and forwards rich notifications to Slack or Microsoft Teams. No license key required. Add a Team license key for persisted server-side history and higher rate limits.

curl -L -X POST https://schemalens.tech/api/schema-drift-webhook \
  -H "Content-Type: application/json" \
  -d '{
    "oldSchema": "CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(255));",
    "newSchema": "CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(255), email VARCHAR(255) NOT NULL);",
    "dialect": "postgres",
    "metadata": {
      "repo": "myorg/myrepo",
      "branch": "feature/add-email",
      "commit": "abc123",
      "ciProvider": "github-actions",
      "runId": "123456"
    },
    "notify": {
      "slack": "https://hooks.slack.com/services/...",
      "teams": "https://outlook.office.com/webhook/..."
    }
  }'Copy

Response: tier, alertId, alertUrl, summary, riskScore, and notificationsSent.
Free tier: no license key required. Data is encoded in the alert URL and never stored server-side.
Team tier: add projectToken with a Team license key for persisted history and 60 alerts/minute.

📊 Open Team Dashboard → 🔔 See Sample Alert →

🤖 MCP Server — Use SchemaLens Inside Claude, Cursor & VS Code

Connect SchemaLens to any MCP-compatible AI assistant. The server exposes three tools for schema diff, migration generation, and breaking-change detection. It runs locally using the same engine as the web app.

• schemalens_diff_schemas — semantic diff with risk score
• schemalens_generate_migration — forward + rollback SQL
• schemalens_detect_breaking_changes — breaking changes with severity

Setup Guide →

🎮 Interactive Playground — Try the Free Diff API

Paste two schemas below and hit Run API Request to see the live response. No signup required.

// Response will appear hereCopy

curl -L -X POST https://schemalens.tech/api/free-diff -H "Content-Type: application/json" -d '{...}'Copy

📤 Step 3 — Understand the Response

{
  "diff": {
    "tablesAdded": [],
    "tablesRemoved": [],
    "tablesModified": [
      {
        "name": "users",
        "columnsAdded": [{ "name": "email", "type": "VARCHAR(255)", ... }],
        "columnsRemoved": [],
        "columnsModified": []
      }
    ],
    "enumsAdded": [],
    "enumsRemoved": [],
    "triggersAdded": [],
    "triggersRemoved": [],
    "triggersModified": [],
    "viewsAdded": [],
    "viewsRemoved": [],
    "viewsModified": [],
    "functionsAdded": [],
    "functionsRemoved": [],
    "functionsModified": []
  },
  "migration": "ALTER TABLE \"users\" ADD \"email\" VARCHAR ( 255 );",
  "breakingChanges": [],
  "riskScore": {
    "score": 0,
    "label": "Safe",
    "icon": "🟢"
  },
  "summary": {
    "tablesAdded": 0,
    "tablesRemoved": 0,
    "tablesModified": 1,
    "enumsAdded": 0,
    "enumsRemoved": 0,
    "triggersAdded": 0,
    "triggersRemoved": 0,
    "triggersModified": 0,
    "viewsAdded": 0,
    "viewsRemoved": 0,
    "viewsModified": 0,
    "functionsAdded": 0,
    "functionsRemoved": 0,
    "functionsModified": 0,
    "breakingChangeCount": 0
  }
}Copy

Response Fields

diff

Full semantic diff with added, removed, and modified tables, columns, constraints, indexes, enums, triggers, views, and functions.

migration

Generated ALTER TABLE / CREATE TABLE SQL to migrate from schemaA to schemaB.

breakingChanges

Array of dangerous changes (DROP_TABLE, DROP_COLUMN, ADD_NOT_NULL_NO_DEFAULT, etc.). Empty if safe.

riskScore

Object with score (0-100), label (Safe / Low / Medium / High / Critical), and icon.

summary

Counts of all object changes for quick dashboard display.

🛠️ Step 4 — Common Patterns

Pattern A: Fail a CI Build on Breaking Changes

#!/bin/bash
set -e

RESPONSE=$(curl -sL -X POST https://schemalens.tech/api/diff \
  -H "Content-Type: application/json" \
  -H "X-License-Key: $SCHEMALENS_KEY" \
  -d "{\"schemaA\":$(cat base.sql | jq -Rs .),\"schemaB\":$(cat head.sql | jq -Rs .),\"dialect\":\"postgres\"}")

COUNT=$(echo "$RESPONSE" | jq '.summary.breakingChangeCount')
if [ "$COUNT" -gt 0 ]; then
  echo "❌ Breaking changes detected:"
  echo "$RESPONSE" | jq '.breakingChanges'
  exit 1
fi

echo "✅ Schema diff passed. No breaking changes."Copy

Pattern B: Post Diff Summary to Slack

# First, get the diff
DIFF=$(curl -sL -X POST https://schemalens.tech/api/diff \
  -H "Content-Type: application/json" \
  -H "X-License-Key: $SCHEMALENS_KEY" \
  -d '{"schemaA":"...","schemaB":"...","dialect":"postgres"}')

# Then, send to Slack via SchemaLens webhook proxy
curl -L -X POST https://schemalens.tech/api/slack \
  -H "Content-Type: application/json" \
  -d "{
    \"webhookUrl\": \"$SLACK_WEBHOOK_URL\",
    \"diff\": $(echo "$DIFF" | jq '.diff'),
    \"migration\": $(echo "$DIFF" | jq '.migration'),
    \"breakingChanges\": $(echo "$DIFF" | jq '.breakingChanges'),
    \"dialect\": \"postgres\"
  }"Copy

Pattern C: Markdown Report for PR Comments

curl -L -X POST https://schemalens.tech/api/diff \
  -H "Content-Type: application/json" \
  -H "X-License-Key: SL-XXXX-XXXX-XXXX-XXXX" \
  -d '{
    "schemaA": "...",
    "schemaB": "...",
    "dialect": "postgres",
    "format": "markdown"
  }' | jq -r '.markdown' > schema-diff-report.md

# Post the markdown to GitHub PR comment via gh CLI
gh pr comment 42 --body-file schema-diff-report.mdCopy

⚠️ Error Handling

📋 Parameters Reference

🔒 Privacy & Limits

• Stateless: Schema data is processed in-memory and never stored or logged.
• Rate limit: 30 requests per minute per IP address.
• No external dependencies: The API runs on Vercel's edge network with sub-100ms response times.
• CORS enabled: Call the API from any domain, including localhost during development.

💻 CLI Alternative

For offline use or air-gapped environments, the SchemaLens CLI provides the same engine without network requests.

node ci/schemalens-diff.js schemaA.sql schemaB.sql --dialect=postgres --format=jsonCopy