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: clu1a2b3c4d5e6f7g8h9i0j1curl -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: clu1a2b3c4d5e6f7g8h9i0j1Response (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
doneimport 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
| Score | Category | Description |
|---|---|---|
overall | Combined | Weighted average of all categories |
ux | User Experience | Usability, interaction patterns, visual design |
accessibility | Accessibility | WCAG compliance, screen reader support |
information_architecture | IA | Navigation, content structure, findability |
performance | Performance | Load times, core web vitals impact on UX |
Understanding Issues
| Severity | Action Required |
|---|---|
error | Critical issues that must be fixed |
warning | Important issues that should be addressed |
info | Suggestions 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
Create Audit Reference
Full endpoint documentation with all parameters
Set Up Webhooks
Get notified when audits complete instead of polling
Error Handling
Handle errors and edge cases gracefully
Use the SDK
TypeScript SDK with built-in polling and error handling
Was this page helpful?