API reference

The endpoints, their parameters, and the exact shape of the responses.

All requests go to https://api.agent-readiness.com. Bodies are JSON, and so are responses — with one exception, the HTML report.

Authentication

By API key, in the Authorization header, with the Bearer prefix.

http

Authorization: Bearer ar_live_xxxxxxxxxxxx

The header is optional when creating an audit: without it, the audit runs anonymously, with tighter limits. But if it's present and invalid, the request fails outright — never a silent fallback to anonymous. A revoked key should be visible, not guessed at.

POST /audits

Creates an audit and queues it. Returns 201 without waiting for it to run.

Field	Type	Default	Purpose
business	string	— (required)	URL of the store to audit. Passed to the engine verbatim.
options	object	{}	Execution parameters — detailed below.
metadata	object	null	CI provenance. Never read by the engine, only stored alongside the audit.

options

Field	Type	Default	Purpose
agent_simulation	boolean	false	Enables the language-model agent simulation. Consumes your monthly quota.
sample_size	integer	20	Number of products sampled for catalog quality.
country	string	"FR"	Market the catalog is queried under.
language	"fr" \| "en"	"fr"	Language of the recommendations and the HTML report.

An unknown field fails loudly

Any unknown field is rejected with a 422, at the root level as well as inside options. This is deliberate: a language placed next to options instead of inside it used to be silently ignored, producing a report in the wrong language with nothing to signal it. A malformed body must fail loudly.

metadata

Three optional string fields: commit_sha, branch, ci_run_url. They tie an audit to whatever triggered it and show up as-is in the dashboard history. The command line fills them in automatically.

json

{
  "business": "https://my-store.com",
  "options": { "agent_simulation": true, "language": "en" },
  "metadata": {
    "commit_sha": "a1b2c3d",
    "branch": "main",
    "ci_run_url": "https://github.com/org/repo/actions/runs/42"
  }
}

GET /audits/{id}

The audit's state and, once finished, its full result.

status	Meaning
pending	Queued, not picked up yet.
running	Currently executing.
done	Finished. result is populated.
failed	The audit couldn't complete. error describes why.

json

{
  "id": "b3f1e2a0-...",
  "status": "done",
  "result": {
    "business": "https://my-store.com",
    "overall_score": 92,
    "checks": [
      { "check_id": "ucp_discovery", "status": "pass", "score": 100, "recommendation": "..." },
      { "check_id": "catalog_quality", "status": "pass", "score": 95, "recommendation": "..." }
    ]
  },
  "agent_brief": "# Audit of https://my-store.com\n...",
  "metadata": { "commit_sha": "a1b2c3d", "branch": "main", "ci_run_url": "..." }
}

Each check carries its own status, score and recommendation — actionable text, written to be read by whoever will fix it. The agent_brief field, present only when something still needs fixing, is that same material reshaped into a Markdown instruction you can paste straight into a coding assistant.

GET /audits/{id}/report

The full HTML report, self-contained and shareable. Returns 404 until the audit reaches done.

Read access: the important part

The audit id is the read credential

Both read endpoints require no authentication. The audit id is itself the access capability: whoever holds it can read the result and the report. This is a design choice — reports are shareable by nature, including with someone who has no account.

The practical consequence follows: treat an audit id as something not to scatter around. Avoid leaving it in the logs of a public build or in a pull request comment on an open repository. To show a score publicly, the CI badge is built for exactly that — it exposes the score, and nothing else.

Account endpoints

The /account/* endpoints (profile, usage, keys, badges) exist but authenticate only with a dashboard session, not with an API key. A script therefore can't yet check its remaining quota before launching an audit; in the meantime, the 402 error body carries that information at the moment it becomes useful.