SDK Quickstart

Create your first UX audit using the VertaaUX TypeScript SDK.

Prerequisites: You need Node.js 18+ and a VertaaUX API key. See Installation for detailed setup.

5-Minute Guide

Install the SDK

Add the VertaaUX SDK to your project:

npm install @vertaaux/sdk

Import and Create Client

Import the SDK and initialize a client with your API key:

import { VertaaUX } from '@vertaaux/sdk';

const client = new VertaaUX({
  apiKey: process.env.VERTAAUX_API_KEY!,
});

Never hardcode your API key. Use environment variables or a secrets manager.

Create an Audit

Submit a URL for UX and accessibility analysis:

const job = await client.audits.create({
  url: 'https://example.com',
});

console.log('Audit job started:', job.job_id);
console.log('Status:', job.status); // "queued"

The API returns immediately with a job_id. Audits run asynchronously in the background.

Poll for Results

Check the audit status until it completes:

let result;
do {
  result = await client.audits.get(job.job_id);
  console.log(`Status: ${result.status}, Progress: ${result.progress}%`);

  if (result.status === 'queued' || result.status === 'running') {
    await new Promise((r) => setTimeout(r, 2000)); // Wait 2 seconds
  }
} while (result.status === 'queued' || result.status === 'running');

For production use, consider using webhooks instead of polling.

Handle Results

Process the completed audit results:

if (result.status === 'completed') {
  console.log('\n--- Audit Complete ---');
  console.log('Overall Score:', result.scores?.overall);
  console.log('UX Score:', result.scores?.ux);
  console.log('Accessibility Score:', result.scores?.accessibility);
  console.log('Issues Found:', result.issues?.length);

  // Display top issues
  result.issues?.slice(0, 3).forEach((issue, i) => {
    console.log(`\n${i + 1}. [${issue.severity}] ${issue.description}`);
    console.log(`   Fix: ${issue.recommendation}`);
  });
} else if (result.status === 'failed') {
  console.error('Audit failed:', result.error);
}

Complete Example

Here's the full script you can run:

audit-example.ts

import { VertaaUX } from '@vertaaux/sdk';

async function runAudit() {
  // Initialize client
  const client = new VertaaUX({
    apiKey: process.env.VERTAAUX_API_KEY!,
  });

  // Create audit
  console.log('Starting audit...');
  const job = await client.audits.create({
    url: 'https://example.com',
    mode: 'basic',
  });
  console.log('Job ID:', job.job_id);

  // Poll for completion
  let result;
  do {
    result = await client.audits.get(job.job_id);
    console.log(`Progress: ${result.progress}%`);
    if (result.status === 'queued' || result.status === 'running') {
      await new Promise((r) => setTimeout(r, 2000));
    }
  } while (result.status === 'queued' || result.status === 'running');

  // Display results
  if (result.status === 'completed') {
    console.log('\nResults:');
    console.log('- Overall:', result.scores?.overall);
    console.log('- Issues:', result.issues?.length);
  } else {
    console.error('Failed:', result.error);
  }
}

runAudit().catch(console.error);

Run with:

VERTAAUX_API_KEY=vx_live_xxx npx tsx audit-example.ts

Try It Live

Interactive Sandbox: Run this example directly in your browser. The sandbox uses a demo API key with simulated responses.

Sandbox Preview

Interactive embeds were replaced with a static, keyboard-safe preview.

This example uses the @vertaaux/sdk package with the react-ts template. Copy the example into your editor to run it locally. Console output is included in the sample flow.

/App.tsx

import { VertaaUX } from '@vertaaux/sdk';

// Demo sandbox - API calls are simulated
const client = new VertaaUX({
apiKey: 'vx_test_demo_sandbox',
});

async function runAudit() {
console.log('Starting audit...');

// In sandbox mode, this simulates the API response
const job = await client.audits.create({
  url: 'https://example.com',
  mode: 'basic',
});

console.log('Job ID:', job.job_id);
console.log('Status:', job.status);

// Simulate polling
console.log('\nAudit would poll for results here...');
console.log('In production, this takes 30-60 seconds.');
}

runAudit().catch(console.error);

/index.tsx

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(<App />);

Expected Output

Starting audit...
Job ID: clu1a2b3c4d5e6f7g8h9i0j1
Progress: 0%
Progress: 25%
Progress: 75%
Progress: 100%

Results:
- Overall: 85
- Issues: 12

Next Steps

Audit Methods Reference

Full documentation for create() and get() methods

Error Handling

Handle rate limits, validation errors, and failures

Webhooks

Get notified when audits complete instead of polling

Was this page helpful?