Start a behavioral-simulation audit of a URL

Starts an async audit job. The job runs a synthetic audience against the target URL and produces predicted UX friction, hesitation, drop-off, and messaging-clarity findings. Poll /api/audits/jobs/{jobId} for status.

post/api/audits/run

Request

  • Base URL: https://api.aetherya.ai
  • URL: https://api.aetherya.ai/api/audits/run
  • Auth: HTTP bearer

Headers

X-Aetherya-Workspace-Idstring

Optional for auth.md delegated tokens (their human-approved workspace is bound into the token); legacy API-key calls may include this header to select a workspace.

Request body

targetstring uri required

The URL to audit.

typestring[] required

Audit type(s). ["ux_ui"] for a page audit, ["ux_journey"] for a multi-step flow.

cognitiveModeboolean

Enable cognitive/behavioral persona simulation. Required to get persona-level findings.

numAgentsinteger

Number of synthetic personas to simulate.

auditDepthinteger

How many pages to crawl.

additionalInstructionsstring

Plain-language focus or audience guidance for the simulation.

personasstring[]

Optional list of persona ids to pin the simulation to.

modelTierstring

Optional simulation quality tier.

Example request

{
  "type": [
    "ux_ui"
  ]
}

Response

Audit job started successfully.

successboolean required
jobIdstring required
messagestring

Changes

No recorded changes to this operation across all 1 revision of this API.