API reference

Audits

Score the catalog against the 12 agent-readiness rules and read the results programmatically.

Get audit results

GET/api/v1/audit

The latest audit run and the current findings snapshot. Requires the read scope.

bash

curl https://useshelfready.com/api/v1/audit \
  -H "Authorization: Bearer $SHELFREADY_API_KEY"

response.json

{
  "data": {
    "last_run": {
      "run_id": "0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0",
      "status": "succeeded",
      "stats": { "catalogScore": 72, "grade": "B", "items": 128, "findings": 41 },
      "started_at": "2026-07-17T09:12:00.000Z",
      "finished_at": "2026-07-17T09:12:04.000Z"
    },
    "findings": [
      {
        "product_id": "5b6c7d8e-9fa0-b1c2-d3e4-f5a6b7c8d9e0",
        "variant_id": null,
        "code": "gtin_missing",
        "severity": "warning",
        "field": "gtin",
        "message": "No GTIN — the #1 discoverability signal for AI shopping surfaces"
      }
    ]
  }
}

Run the audit

POST/api/v1/audit/runs

Score the catalog for agent readiness now. Synchronous — the response carries the catalog score (0–100) and grade (A–F). A failed audit returns 422. Requires the write scope. Audits also run automatically after every sync, and each run emits an audit.completed webhook.

run.sh

curl -X POST https://useshelfready.com/api/v1/audit/runs \
  -H "Authorization: Bearer $SHELFREADY_API_KEY"

response.json

{
  "data": {
    "run_id": "0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0",
    "catalog_score": 72,
    "grade": "B"
  }
}

The finding object

Findings are rule violations; see running an audit for all 12 rule codes, severities, and weights.

Parameter	Type	Description
`product_id`	uuid \| null	The product the finding points at (null for catalog-level findings).
`variant_id`	uuid \| null	The variant, when the finding is variant-specific.
`code`	string	Rule code, e.g. gtin_missing or url_not_https.
`severity`	string	error, warning, or info.
`field`	string \| null	The canonical field the finding is about.
`message`	string	Human-readable explanation.