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.VERTAA_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.VERTAA_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:

VERTAA_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.

Loading sandbox...

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?

SDK Quickstart

Audit Methods Reference

Error Handling

Webhooks

On this page