Create Audit
Start a new UX audit job for any URL
Create Audit
/v1/auditStart 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
| Parameter | Type | Required | Description |
|---|---|---|---|
| url | string | required | The URL to audit. Must be a valid HTTP or HTTPS URL accessible from the internet. |
| mode | string | optional | Audit depth. Determines the thoroughness of the analysis.Default: basic |
| ↳basic | enum | optional | Single page, fast (~30s). Good for quick checks. |
| ↳standard | enum | optional | Up to 5 pages, follows navigation (~2min). Recommended for most use cases. |
| ↳deep | enum | optional | Up to 20 pages, comprehensive analysis (~5min). Best for production audits. |
| timeout | number | optional | Maximum time in milliseconds to wait for the page to load.Default: 30000 |
| user_agent | string | optional | Custom User-Agent string for the audit browser. |
| fail_on_score | number | optional | Threshold 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_drop | number | optional | Score 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_idstringUnique identifier for the audit job. Use this to poll for results.
statusstringenum: queuedCurrent job status. Always 'queued' for new jobs.
urlstringThe URL being audited (echoed from request).
modestringThe audit mode (echoed from request).
engine_versionstringVersion of the audit engine processing this job.
ruleset_versionstringVersion of the UX ruleset being applied.
created_atstringISO 8601 timestamp when the job was created.
sandboxbooleanWhether 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
| Status | Description |
|---|---|
202 Accepted | Audit job created successfully. Poll for results using the job_id. |
400 Bad Request | Invalid request body. Check the url format and mode value. |
401 Unauthorized | Missing or invalid API key. |
429 Too Many Requests | Rate limit or quota exceeded. Check Retry-After header. |
500 Internal Server Error | Server 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: 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": "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: clu1a2b3c4d5e6f7g8h9i0j1Idempotency
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 Conflicterror
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
Related
Get Audit
Poll for audit results and status
Webhooks
Get notified when audits complete
Error Handling
Handle errors gracefully
Was this page helpful?