Skip to main content
VertaaUX Docs
APIEndpoints

Create Audit

Start a new UX audit job for any URL

Create Audit

POST/v1/audit

Start a new UX audit job. The audit runs asynchronously - use the returned job_id to poll for results or configure webhooks for completion notifications.

Request Body

ParameterTypeRequiredDescription
urlstringrequiredThe URL to audit. Must be a valid HTTP or HTTPS URL accessible from the internet.
modestringoptionalAudit depth. Determines the thoroughness of the analysis.Default: basic
basicenumoptionalSingle page, fast (~30s). Good for quick checks.
standardenumoptionalUp to 5 pages, follows navigation (~2min). Recommended for most use cases.
deepenumoptionalUp to 20 pages, comprehensive analysis (~5min). Best for production audits.
timeoutnumberoptionalMaximum time in milliseconds to wait for the page to load.Default: 30000
user_agentstringoptionalCustom User-Agent string for the audit browser.
fail_on_scorenumberoptionalThreshold score (0-100). If the overall score is below this value, the audit status will be 'failed'. Useful for CI/CD quality gates.
fail_on_dropnumberoptionalScore drop threshold (0-100). If the score drops by more than this amount compared to the previous audit of the same URL, status will be 'failed'.

Response

job_idstring

Unique identifier for the audit job. Use this to poll for results.

statusstringenum: queued

Current job status. Always 'queued' for new jobs.

urlstring

The URL being audited (echoed from request).

modestring

The audit mode (echoed from request).

engine_versionstring

Version of the audit engine processing this job.

ruleset_versionstring

Version of the UX ruleset being applied.

created_atstring

ISO 8601 timestamp when the job was created.

sandboxboolean

Whether this audit is running in sandbox mode.

Example Response (202 Accepted)

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

HTTP Status Codes

StatusDescription
202 AcceptedAudit job created successfully. Poll for results using the job_id.
400 Bad RequestInvalid request body. Check the url format and mode value.
401 UnauthorizedMissing or invalid API key.
429 Too Many RequestsRate limit or quota exceeded. Check Retry-After header.
500 Internal Server ErrorServer error. Retry with exponential backoff.

Code Examples

import 'dotenv/config';

interface AuditResponse {
  job_id: string;
  status: string;
  url: string;
  mode: string;
  engine_version: string;
  ruleset_version: string;
  created_at: string;
  sandbox: boolean;
}

async function createAudit(url: string, mode: 'basic' | 'standard' | 'deep' = 'basic'): Promise<AuditResponse> {
  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,
      mode,
    }),
  });

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

  return response.json();
}

// Usage
const audit = await createAudit('https://example.com', 'standard');
console.log(`Audit created: ${audit.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": "standard"
  }'

Response:

{
  "job_id": "clu1a2b3c4d5e6f7g8h9i0j1",
  "status": "queued",
  "url": "https://example.com",
  "mode": "standard",
  "engine_version": "latest",
  "ruleset_version": "2024.1",
  "created_at": "2024-01-15T10:30:00Z",
  "sandbox": false
}
import os
import requests
from typing import TypedDict, Literal

class AuditResponse(TypedDict):
    job_id: str
    status: str
    url: str
    mode: str
    engine_version: str
    ruleset_version: str
    created_at: str
    sandbox: bool

def create_audit(
    url: str,
    mode: Literal['basic', 'standard', 'deep'] = 'basic'
) -> AuditResponse:
    """Create a new UX audit job."""
    response = requests.post(
        'https://vertaaux.ai/api/v1/audit',
        headers={
            'X-API-Key': os.environ['VERTAAUX_API_KEY'],
            'Content-Type': 'application/json',
        },
        json={
            'url': url,
            'mode': mode,
        }
    )

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

    return response.json()

# Usage
audit = create_audit('https://example.com', 'standard')
print(f"Audit created: {audit['job_id']}")
# Output: Audit created: clu1a2b3c4d5e6f7g8h9i0j1

Idempotency

Use the Idempotency-Key header to safely retry requests without creating duplicate audits:

curl -X POST https://vertaaux.ai/api/v1/audit \
  -H "X-API-Key: $VERTAAUX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key-12345" \
  -d '{"url": "https://example.com"}'
  • Keys must be unique per API key and are valid for 24 hours
  • Maximum length: 128 characters
  • If the same idempotency key is used with different parameters, you will receive a 409 Conflict error

CI/CD Integration

Use fail_on_score and fail_on_drop for automated quality gates:

# Fail if score drops below 80
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": "standard",
    "fail_on_score": 80
  }'

# Fail if score drops more than 5 points from previous audit
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": "standard",
    "fail_on_drop": 5
  }'

What's Next

After creating an audit, poll for results using the Get Audit endpoint, or configure Webhooks for completion notifications.

Also Available

InterfaceCommand/Method
CLIvertaa audit https://example.com
SDKclient.audits.create({ url: '...' })

Was this page helpful?

On this page