Skip to main content
VertaaUX Docs
API

API Quickstart

Make your first API request in 5 minutes

API Quickstart

This guide walks you through making your first UX audit using the VertaaUX REST API.

Prerequisites

Before you begin, you need an API key. See Authentication for how to create and manage API keys.

Use a test key (vx_test_...) during development to avoid consuming your quota.

Step 1: Create an Audit

Start a UX audit by sending a POST request to /v1/audit:

const response = await fetch('https://vertaaux.ai/api/v1/audit', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.VERTAAUX_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    mode: 'basic',
  }),
});

const data = await response.json();
console.log('Audit created:', data.job_id);
// Output: Audit created: clu1a2b3c4d5e6f7g8h9i0j1
curl -X POST https://vertaaux.ai/api/v1/audit \
  -H "X-API-Key: $VERTAAUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "mode": "basic"
  }'
import os
import requests

response = requests.post(
    'https://vertaaux.ai/api/v1/audit',
    headers={
        'X-API-Key': os.environ['VERTAAUX_API_KEY'],
        'Content-Type': 'application/json',
    },
    json={
        'url': 'https://example.com',
        'mode': 'basic',
    }
)

data = response.json()
print(f"Audit created: {data['job_id']}")
# Output: Audit created: clu1a2b3c4d5e6f7g8h9i0j1

Response (202 Accepted):

{
  "job_id": "clu1a2b3c4d5e6f7g8h9i0j1",
  "status": "queued",
  "url": "https://example.com",
  "mode": "basic",
  "ruleset_version": "2024.1",
  "created_at": "2024-01-15T10:30:00Z"
}

Save the job_id - you will use it to check the audit status.

Step 2: Poll for Results

Audits run asynchronously. Poll the status endpoint until the audit completes:

async function waitForAudit(jobId: string): Promise<AuditResult> {
  const apiKey = process.env.VERTAAUX_API_KEY!;

  while (true) {
    const response = await fetch(
      `https://vertaaux.ai/api/v1/audit/${jobId}`,
      {
        headers: { 'X-API-Key': apiKey },
      }
    );

    const data = await response.json();

    if (data.status === 'completed') {
      return data;
    }

    if (data.status === 'failed') {
      throw new Error(`Audit failed: ${data.error}`);
    }

    // Wait 2 seconds before polling again
    console.log(`Status: ${data.status}, progress: ${data.progress}%`);
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}

const result = await waitForAudit('clu1a2b3c4d5e6f7g8h9i0j1');
console.log('Overall score:', result.scores.overall);
# Poll until status is "completed" or "failed"
while true; do
  RESULT=$(curl -s https://vertaaux.ai/api/v1/audit/$JOB_ID \
    -H "X-API-Key: $VERTAAUX_API_KEY")

  STATUS=$(echo $RESULT | jq -r '.status')

  if [ "$STATUS" = "completed" ]; then
    echo "Audit complete!"
    echo $RESULT | jq '.scores'
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Audit failed: $(echo $RESULT | jq -r '.error')"
    exit 1
  fi

  echo "Status: $STATUS, waiting..."
  sleep 2
done
import os
import time
import requests

def wait_for_audit(job_id: str) -> dict:
    api_key = os.environ['VERTAAUX_API_KEY']

    while True:
        response = requests.get(
            f'https://vertaaux.ai/api/v1/audit/{job_id}',
            headers={'X-API-Key': api_key}
        )

        data = response.json()

        if data['status'] == 'completed':
            return data

        if data['status'] == 'failed':
            raise Exception(f"Audit failed: {data.get('error')}")

        print(f"Status: {data['status']}, progress: {data['progress']}%")
        time.sleep(2)

result = wait_for_audit('clu1a2b3c4d5e6f7g8h9i0j1')
print(f"Overall score: {result['scores']['overall']}")

Step 3: View Results

Once the audit completes, you will receive scores and issues:

{
  "job_id": "clu1a2b3c4d5e6f7g8h9i0j1",
  "status": "completed",
  "url": "https://example.com",
  "progress": 100,
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:31:15Z",
  "scores": {
    "overall": 85,
    "ux": 88,
    "accessibility": 82,
    "information_architecture": 86,
    "performance": 84
  },
  "issues": [
    {
      "id": "issue_1",
      "severity": "warning",
      "category": "accessibility",
      "rule": "color-contrast",
      "message": "Text has insufficient color contrast",
      "selector": "#hero-subtitle",
      "wcag": "1.4.3"
    },
    {
      "id": "issue_2",
      "severity": "error",
      "category": "ux",
      "rule": "touch-target-size",
      "message": "Touch target is too small (32x32px, minimum 44x44px)",
      "selector": ".mobile-nav-toggle"
    }
  ],
  "total_issues": 2
}

Understanding Scores

ScoreCategoryDescription
overallCombinedWeighted average of all categories
uxUser ExperienceUsability, interaction patterns, visual design
accessibilityAccessibilityWCAG compliance, screen reader support
information_architectureIANavigation, content structure, findability
performancePerformanceLoad times, core web vitals impact on UX

Understanding Issues

SeverityAction Required
errorCritical issues that must be fixed
warningImportant issues that should be addressed
infoSuggestions for improvement

Complete Example

Here is a complete script that creates an audit and displays results:

import 'dotenv/config';

const API_KEY = process.env.VERTAAUX_API_KEY!;
const BASE_URL = 'https://vertaaux.ai/api/v1';

async function runAudit(url: string) {
  // Create audit
  const createRes = await fetch(`${BASE_URL}/audit`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ url, mode: 'basic' }),
  });

  if (!createRes.ok) {
    const error = await createRes.json();
    throw new Error(`Failed to create audit: ${error.message}`);
  }

  const { job_id } = await createRes.json();
  console.log(`Audit started: ${job_id}`);

  // Poll for results
  while (true) {
    const statusRes = await fetch(`${BASE_URL}/audit/${job_id}`, {
      headers: { 'X-API-Key': API_KEY },
    });

    const result = await statusRes.json();

    if (result.status === 'completed') {
      console.log('\n--- Audit Results ---');
      console.log(`URL: ${result.url}`);
      console.log(`Overall Score: ${result.scores.overall}/100`);
      console.log(`Issues Found: ${result.total_issues}`);

      const errors = result.issues.filter(i => i.severity === 'error');
      const warnings = result.issues.filter(i => i.severity === 'warning');

      console.log(`  - Errors: ${errors.length}`);
      console.log(`  - Warnings: ${warnings.length}`);

      return result;
    }

    if (result.status === 'failed') {
      throw new Error(`Audit failed: ${result.error}`);
    }

    process.stdout.write(`\rProgress: ${result.progress}%`);
    await new Promise(r => setTimeout(r, 2000));
  }
}

// Run it
runAudit('https://example.com')
  .then(() => process.exit(0))
  .catch(err => {
    console.error(err.message);
    process.exit(1);
  });
#!/usr/bin/env python3
import os
import sys
import time
import requests

API_KEY = os.environ.get('VERTAAUX_API_KEY')
BASE_URL = 'https://vertaaux.ai/api/v1'

def run_audit(url: str) -> dict:
    headers = {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json',
    }

    # Create audit
    response = requests.post(
        f'{BASE_URL}/audit',
        headers=headers,
        json={'url': url, 'mode': 'basic'}
    )

    if not response.ok:
        error = response.json()
        raise Exception(f"Failed to create audit: {error.get('message')}")

    job_id = response.json()['job_id']
    print(f"Audit started: {job_id}")

    # Poll for results
    while True:
        response = requests.get(
            f'{BASE_URL}/audit/{job_id}',
            headers={'X-API-Key': API_KEY}
        )

        result = response.json()

        if result['status'] == 'completed':
            print('\n--- Audit Results ---')
            print(f"URL: {result['url']}")
            print(f"Overall Score: {result['scores']['overall']}/100")
            print(f"Issues Found: {result['total_issues']}")

            errors = [i for i in result['issues'] if i['severity'] == 'error']
            warnings = [i for i in result['issues'] if i['severity'] == 'warning']

            print(f"  - Errors: {len(errors)}")
            print(f"  - Warnings: {len(warnings)}")

            return result

        if result['status'] == 'failed':
            raise Exception(f"Audit failed: {result.get('error')}")

        print(f"\rProgress: {result['progress']}%", end='', flush=True)
        time.sleep(2)

if __name__ == '__main__':
    if not API_KEY:
        print('Error: VERTAAUX_API_KEY environment variable not set')
        sys.exit(1)

    try:
        run_audit('https://example.com')
    except Exception as e:
        print(f'Error: {e}')
        sys.exit(1)

Next Steps

Was this page helpful?

On this page