Overview

VertaaUX gives you programmatic audits across usability, information architecture, accessibility, and conversion signals. The API is fully asynchronous: start an audit, receive a job_id, then poll or subscribe to a webhook for completion. All examples below use the public base URL https://vertaaux.ai/v1.

Authentication

Authenticate every request with an API key using the X-API-Key header. Keep the key in server-side environments or CI secrets; do not expose it to browsers or client-side code.

SDKs & Clients

Official SDK scaffolds are available for JS/TS and Python. They include retries, idempotency helpers, webhook verification, and typed responses. Base URL defaults to production; override for staging/test mode.

import { createVertaauxClient } from "@vertaaux/sdk-js";
const client = createVertaauxClient({ apiKey: "your_api_key_here" });
const audit = await client.createAudit({ url: "https://example.com", mode: "basic" });
const status = await client.getAudit(audit.job_id);

import { createVertaauxClient, generateIdempotencyKey } from "@vertaaux/sdk-js";

	const client = createVertaauxClient({
	  apiKey: "your_api_key_here",
	  baseUrl: "https://vertaaux.ai/v1", // or staging host
	  idempotencyKey: generateIdempotencyKey(),
	});

const audit = await client.createAudit({ url: "https://example.com", mode: "basic" });
const status = await client.getAudit(audit.job_id);

from vertaaux_api_client import AuthenticatedClient
from vertaaux_api_client.api.audits import create_audit, get_audit
from vertaaux_api_client.models import AuditRequest

	client = AuthenticatedClient(
	    base_url="https://vertaaux.ai/v1",
	    token="YOUR_API_KEY",
	)
resp = create_audit.sync(client=client, json_body=AuditRequest(url="https://example.com", mode="basic"))
status = get_audit.sync(client=client, job_id=resp.job_id)

Making Your First Request

curl -X POST https://vertaaux.ai/v1/audit \
  -H "X-API-Key: $VERTAA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "mode": "standard"
  }'

const response = await fetch("https://vertaaux.ai/v1/audit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "your_api_key_here",
  },
  body: JSON.stringify({ url: "https://example.com", mode: "standard" }),
});

const { job_id } = await response.json();

import os, requests

api_key = os.environ["VERTAA_API_KEY"]
payload = {"url": "https://example.com", "mode": "standard"}

res = requests.post(
    "https://vertaaux.ai/v1/audit",
    headers={"X-API-Key": api_key, "Content-Type": "application/json"},
    json=payload,
)
print(res.json()["job_id"])

curl -X GET https://vertaaux.ai/v1/audit/{job_id} \
  -H "X-API-Key: $VERTAA_API_KEY"

const res = await fetch(`https://vertaaux.ai/v1/audit/${jobId}`, {
  headers: { "X-API-Key": "your_api_key_here" },
});
const audit = await res.json();

if (audit.status === "completed") {
  console.log(audit.scores, audit.issues?.length);
}

Responses & Error Codes

The audit status endpoint returns the full payload once processing is complete. Common HTTP responses are listed below.

{
  "job_id": "audit_01HF2YAJDQZ98X2M2YB1T5R9SJ",
  "status": "completed",
  "progress": 100,
  "scores": {
    "usability": 92,
    "clarity": 88,
    "ia": 86,
    "accessibility": 90,
    "performance": 82
  },
  "issues": [
    {
      "id": "iss_001",
      "severity": "high",
      "category": "accessibility",
      "description": "Button lacks accessible label",
      "recommendation": "Add aria-label or text content.",
      "selector": "button.primary",
      "wcag_reference": "2.5.3"
    }
  ],
  "heatmap_prediction": "https://cdn.example.com/heatmaps/audit_01HF2YA.png",
  "version": "1.0.0"
}

{
  "error": "Validation error",
  "message": "Quota exceeded",
  "details": [...]
}

Pagination

Issue payloads support server-side filtering and pagination to avoid oversized responses. Use page and per_page on GET /audit/{job_id} to page through issues. Filters:severity=error|warning|info and fields=severity,selector,category to trim the payload. Responses include total and total_pages.

Streaming is available for large sets: GET /audit/{job_id}/issues/stream returns NDJSON so you can process issues incrementally.

Webhooks

Receive a POST callback when an audit finishes. Register a target URL and optional signing secret using POST /webhooks.

// Node/TS
import { verifyWebhookSignature } from "@vertaaux/sdk-js";
const isValid = await verifyWebhookSignature({
  secret: "your_webhook_secret_here",
  payload: rawBodyString,
  signature: req.headers["x-vertaaux-signature"] as string,
  timestamp: req.headers["x-vertaaux-signature-timestamp"] as string,
  toleranceSeconds: 300,
});

# Python
import hmac, hashlib, time

def verify(secret: str, payload: str, signature: str, timestamp: str, tolerance_seconds: int = 300) -> bool:
    try:
        ts_int = int(timestamp)
    except (TypeError, ValueError):
        return False
    if abs(time.time() - ts_int / 1000) > tolerance_seconds:
        return False
    digest = hmac.new(secret.encode(), f"{timestamp}.{payload}".encode(), hashlib.sha256).hexdigest()
    if len(digest) != len(signature):
        return False
    return hmac.compare_digest(digest, signature)

curl -X POST https://vertaaux.ai/v1/webhooks \
  -H "X-API-Key: $VERTAA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/vertaa",
    "secret": "your-shared-secret"
  }'

import crypto from "crypto";
import { NextRequest, NextResponse } from "next/server";

const secret = "your_webhook_secret_here";

export async function POST(req: NextRequest) {
  const rawBody = await req.text();
  const signature = req.headers.get("x-vertaaux-signature") ?? "";
  const timestamp = req.headers.get("x-vertaaux-signature-timestamp") ?? "";

  if (!timestamp || Math.abs(Date.now() - Number(timestamp)) > 5 * 60 * 1000) {
    return NextResponse.json({ ok: false, reason: "stale" }, { status: 400 });
  }

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  if (signature !== expected) return NextResponse.json({ ok: false }, { status: 401 });
  const payload = JSON.parse(rawBody);
  // payload.job_id, payload.status, payload.completed_at, payload.scores
  return NextResponse.json({ received: true });
}

Rate Limiting & Quotas

The API enforces per-account limits based on your subscription tier. Exceeding limits returns 429 Too Many Requests with rate limit headers.

Next.js Integration

Complete guide for integrating Vertaa in Next.js applications. Covers App Router, Pages Router, webhooks with signature verification, polling with exponential backoff, and caching patterns. Expected integration time: <30 minutes.

SDK Examples

Use your preferred HTTP client; the API is language-agnostic. These snippets show minimal wrappers for common tasks.

import axios from "axios";

const client = axios.create({
  baseURL: "https://vertaaux.ai/v1",
  headers: { "X-API-Key": "your_api_key_here" },
});

export async function runAudit(url: string) {
  const { data } = await client.post("/audit", { url, mode: "basic" });
  return data.job_id;
}

import requests, os

BASE_URL = "https://vertaaux.ai/v1"
HEADERS = {"X-API-Key": os.environ["VERTAA_API_KEY"]}

def get_quota():
    res = requests.get(f"{BASE_URL}/quota", headers=HEADERS, timeout=10)
    res.raise_for_status()
    return res.json()

def delete_webhook(webhook_id: str):
    res = requests.delete(f"{BASE_URL}/webhooks/{webhook_id}", headers=HEADERS)
    return res.status_code == 204

API Explorer

Interactive Swagger UI documentation for testing API endpoints directly from your browser. Explore schemas, try live requests, and generate code snippets.

Troubleshooting

Scheduled Audits

Enterprise and Agency tiers can configure recurring audits with cron expressions. Receive email and webhook notifications when scores drop or audits fail.

Organizations & SSO

Agency and Enterprise tiers support multi-tenant organizations with SSO auto-join capabilities for domain-based onboarding.

{
  "url": "https://example.com",
  "mode": "standard",
  "organization_id": "org_xxxxx"
}

Error Codes Reference

Comprehensive catalog of all API error codes with causes, resolutions, and examples.

Versioning & Deprecation Policy

Learn about our API version lifecycle, breaking change notifications, and 12-month deprecation process.

Service Level Agreement

Uptime and response-time targets available via Enterprise agreement, plus incident-response commitments and credits (by contract).