One audit contract for people and agents.
Every structured report is available through a stable, read-only endpoint. The browser report, JSON, and Markdown are generated from the same reconciliation model, so scores and result states cannot drift by format.
Versioned endpoint
Use the normalized storefront domain. Add the workflow query parameter when you need the immutable result from one specific run instead of the latest completed audit.
GET https://audit.bily.ai/api/v1/public-audits/cozyearth.com GET https://audit.bily.ai/api/v1/public-audits/cozyearth.com?workflow=audit_...
Markdown
Request Markdown through content negotiation or the format query parameter. It contains the five areas, all five journey stages, verified priorities, every check state, and coverage limits.
curl -H 'Accept: text/markdown' \ https://audit.bily.ai/api/v1/public-audits/cozyearth.com # equivalent GET /api/v1/public-audits/cozyearth.com?format=markdown
Result contract
- schemaVersion identifies the response contract.
- score and grade are null unless all six weighted technical categories and every requested regional profile have complete positive-proof coverage; scoreStatus distinguishes final, provisional, and unavailable results.
- scoreRange is an evidence-bounded minimum and maximum for an incomplete run. It is never a final score. scoreCoveragePct states how much of the 100-point model and requested profile set is backed by complete receipts.
- areas always contains the five canonical audit areas. Each area has its own scoreStatus: final areas expose score, partially evaluated areas expose scoreRange, and genuinely unevaluated areas keep both null.
- technicalSubcategories project every weighted category onto a comparable 0–100 scale. scoreRange and earnedPointsRange preserve partial evidence while weightPoints and earnedPoints keep final arithmetic exact.
- consentGovernance.applicability is required, not_required, or undetermined; it separates named scenario capture from verified accept and reject or opt-out action receipts.
- journey always contains page view, product view, add to cart, checkout, and purchase.
- checks uses pass, fail, review, not_exercised, or blocked without collapsing them into a boolean.
- scoreModel.caps contains only evidence-bound public ceilings after reconciliation.
- coverage preserves missing scenarios, semantic warnings, data gaps, and profileCoverage.requested/completed/blocked/unavailable so a 1-of-3 regional run cannot appear final.
- A numeric zero means the measurement ran and observed zero. Missing, blocked, or unexercised measurements are null or explicitly unavailable.
Errors and freshness
Errors use application/problem+json. Successful responses use Cache-Control: no-store. Workflow-bound requests fail closed when the completed archive does not match that workflow, preventing a new run from loading an older result.
Discovery
- OpenAPI: https://audit.bily.ai/openapi.json
- LLM discovery: https://audit.bily.ai/llms.txt
- Methodology: https://audit.bily.ai/methodology