`run_audit`

Starts a full audit run for a brand. Asynchronous — returns immediately with a run_id to poll.

Tier: mutate · Rate limit: 3 per 10 min (plus 3 per 10 min per target domain)

Input

Param	Type	Required	Default	Notes
`domain`	string	✅	—	Bare public hostname, e.g. `acme.com`. 3–253 chars.
`brand_name`	string	✅	—	1–120 chars. As shoppers would refer to it.
`category`	string	✅	—	1–120 chars, e.g. `trail running shoes`.
`competitors`	string[]	—	`[]`	Max 10 items, each 1–120 chars.
`refresh_profile`	boolean	—	unset	Re-read the site and discard the stored brand profile.

Domain validation

domain must be a bare hostname. Rejected: schemes, credentials, ports, paths, query strings, fragments, whitespace, backslashes. It must contain a dot (so localhost is rejected) and its final label must not be all-numeric (so 10.0.0.5 and 169.254.169.254 are rejected). Each label is at most 63 characters.

These rules are an SSRF guard, not tidiness — the audit fetches this host.

`refresh_profile` breaks comparability

Re-extracting the brand profile changes the question set, so the resulting score is not comparable with prior runs. Score deltas will report cross_query_set. Use it when the brand genuinely changed what it sells, not to retry a score you disliked.

category is used only for the generic fallback question set and for grouping in compare_brands. It never determines the archetype.

Output

{
  "run_id": "…",
  "brand_id": "…",
  "status": "pending",
  "message": "Audit started for Acme. Poll get_audit_status with this run_id."
}

status is always pending on return. The pipeline runs after the response is sent.

Example

{
  "domain": "brooklinen.com",
  "brand_name": "Brooklinen",
  "category": "bed sheets",
  "competitors": ["Parachute", "Boll & Branch"]
}

Poll get_audit_status. A run typically completes in a few minutes — up to 20 engine calls plus judging.

run_audit

Input

Domain validation

refresh_profile breaks comparability

Output

Example

Next

`run_audit`

`refresh_profile` breaks comparability