SDK docs

Use Versionly in your apps

Install @wowsql/sma, authenticate with an API key from the dashboard, and trigger scans from Node, Next.js, or CI.

Install

The public package is @wowsql/sma. Requires Node 18+.

bash

npm install @wowsql/sma

# or
pnpm add @wowsql/sma
yarn add @wowsql/sma

Authentication

Sign up at the dashboard.
Choose a plan under Billing (scans need an active subscription).
Open Settings → create an API key (sma_live_…).
Store it as VERSIONLY_API_KEY (or SMA_API_KEY).

import { SmaClient } from "@wowsql/sma";

const sma = new SmaClient({
  apiKey: process.env.VERSIONLY_API_KEY, // sma_live_...
  // baseUrl: "https://api.versionly.dev", // default
});

Option	Env	Default
apiKey	VERSIONLY_API_KEY / SMA_API_KEY	—
baseUrl	SMA_BASE_URL	https://api.versionly.dev

Quick start

Typical flow in an app or script: track vendors → register repos → scan with autoFix: true.

import { SmaClient } from "@wowsql/sma";

const sma = new SmaClient({
  apiKey: process.env.VERSIONLY_API_KEY,
});

// 1. Track a vendor by OpenAPI spec
await sma.addVendor({
  vendorKey: "stripe",
  name: "Stripe",
  specUrl:
    "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json",
  importHints: ["stripe", "@stripe/"],
});

// 2. Register a repo (GitHub App must be installed)
const { repo } = await sma.registerRepo({
  owner: "acme",
  name: "billing-service",
});

// 3. Scan — autoFix opens PRs with suggested fixes
const result = await sma.scan({
  repoId: repo.id,
  autoFix: true,
});

for (const pr of result.pullRequests) {
  console.log("Fix PR:", pr.url);
}

API reference

Main methods on SmaClient.

listVendors()
List third-party APIs you are tracking.
addVendor({ vendorKey, name, specUrl, … })
Start monitoring a vendor OpenAPI spec.
listRepos()
List GitHub repos connected to your workspace.
registerRepo({ owner, name })
Register a repo after installing the Versionly GitHub App.
scan({ repoId?, vendorKey?, autoFix? })
Run a real-time scan. Requires an active plan. autoFix opens PRs.
listScans() / getScan(id)
Inspect past scan runs.
getFindings()
List breaking-change findings across scans.
createApiKey(name)
Create a CI key (plaintext returned once).

MCP

Hosted Model Context Protocol at https://mcp.versionly.dev/mcp. Cursor, Claude, and VS Code authenticate with OAuth — no API key in the config. Scans need an active plan. Auto-fix PRs are included on Scout, Guardian, and Command.

json

{
  "mcpServers": {
    "versionly": {
      "url": "https://mcp.versionly.dev/mcp"
    }
  }
}

Optional URL query: ?repo_id=YOUR_REPO_ID&read_only=true&features=deps,scans. Copy the snippet from dashboard Settings after you sign in.

list_dependencies
Monitored third-party APIs (not npm packages).
check_api_changes
Diff OpenAPI snapshots and changelogs.
analyze_impact
Map changes to files and lines in a connected repo.
explain_breaking_change
Explain a stored finding and how to migrate.
generate_fix
Propose patches. Does not open a PR. Active plan required.
create_pull_request
Open a GitHub fix PR. Never merges. Active plan required.

Use in CI

Add your API key as a GitHub Actions secret, then scan on a schedule or manually.

yml

# .github/workflows/versionly-scan.yml
name: Versionly scan
on:
  schedule:
    - cron: "0 6 * * 1"   # Mondays 06:00 UTC
  workflow_dispatch:

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm install @wowsql/sma
      - name: Run Versionly scan
        env:
          VERSIONLY_API_KEY: ${{ secrets.VERSIONLY_API_KEY }}
        run: node scripts/versionly-scan.mjs

// scripts/versionly-scan.mjs
import { SmaClient } from "@wowsql/sma";

const sma = new SmaClient({ apiKey: process.env.VERSIONLY_API_KEY });
const { repos } = await sma.listRepos();

for (const repo of repos) {
  const result = await sma.scan({ repoId: repo.id, autoFix: true });
  console.log(repo.fullName ?? repo.name, result.status, result.pullRequests);
}

Errors

Failed calls throw SmaError with status, code, and details.

Status	Meaning
401	Missing or invalid API key
402	No active plan — subscribe in Billing before scanning
4xx / 5xx	See error.message for details

Ready to wire it up?

Create a workspace, connect GitHub, grab an API key, then npm install @wowsql/sma.

Open dashboard Back to home