> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asva-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Readiness Score API: POST /api/audit Full Reference

> Audit any domain's agentic commerce readiness — get a 0–100 score, letter grade, prioritised gap list, and category breakdown in one API call.

The Readiness Score API inspects a domain across five capability areas — discoverability, catalog, checkout, schema, and attribution — and returns a single score and a prioritised list of gaps to fix. Use it to assess a domain before implementation begins, to validate after each implementation step, or to run batch audits across multiple client domains. All calls require authentication — see [Authentication](/api-reference/authentication).

## Endpoint

```
POST https://asva-ai.com/api/audit
```

***

## Request parameters

<ParamField body="domain" type="string" required>
  The domain to audit, without `https://`. Example: `"yourstore.com"`
</ParamField>

<ParamField body="checks" type="string[]">
  Specific checks to run. Omit this field to run all checks.

  Available values: `well_known`, `catalog`, `checkout`, `schema`, `feed`, `attribution`, `entity`
</ParamField>

<ParamField body="dry_run" type="boolean">
  When `true`, the API returns a cached result without re-fetching the domain. Use this during development to test your integration without triggering a live audit.
</ParamField>

**What each check tests:**

| Check         | What it tests                                                      |
| ------------- | ------------------------------------------------------------------ |
| `well_known`  | `/.well-known/ucp` presence, validity, and accessibility           |
| `catalog`     | Product catalog endpoint structure and data quality                |
| `checkout`    | UCP/ACP checkout endpoint availability                             |
| `schema`      | JSON-LD `Product`, `Offer`, `Organization` schema on product pages |
| `feed`        | Google Merchant Center feed quality                                |
| `attribution` | Asva attribution snippet presence                                  |
| `entity`      | Entity consistency — brand name and organization schema            |

**Example request:**

```json theme={null}
{
  "domain": "yourstore.com",
  "checks": ["well_known", "catalog", "checkout", "schema", "attribution"],
  "dry_run": false
}
```

***

## Response fields

<ResponseField name="domain" type="string">
  The domain that was audited.
</ResponseField>

<ResponseField name="score" type="integer">
  Overall readiness score from 0 to 100. Higher is better.
</ResponseField>

<ResponseField name="grade" type="string">
  Letter grade based on the score.

  | Grade | Score range |
  | ----- | ----------- |
  | A     | 80–100      |
  | B     | 60–79       |
  | C     | 40–59       |
  | D     | 0–39        |
</ResponseField>

<ResponseField name="checked_at" type="string">
  ISO 8601 timestamp of when the audit ran.
</ResponseField>

<ResponseField name="gaps" type="array">
  Issues found, ordered by severity. Each item in the array contains:

  <ResponseField name="gaps[].id" type="string">
    Unique identifier for this gap type, for example `well_known_missing`.
  </ResponseField>

  <ResponseField name="gaps[].check" type="string">
    Which check category this gap belongs to.
  </ResponseField>

  <ResponseField name="gaps[].severity" type="string">
    How urgently this gap needs fixing: `critical`, `high`, `medium`, or `low`.
  </ResponseField>

  <ResponseField name="gaps[].label" type="string">
    Short human-readable description of the gap.
  </ResponseField>

  <ResponseField name="gaps[].detail" type="string">
    Full explanation of the gap and its impact on AI commerce.
  </ResponseField>

  <ResponseField name="gaps[].fix_url" type="string">
    Link to the relevant Asva tool to fix this gap. May be `null` if no tool applies.
  </ResponseField>
</ResponseField>

<ResponseField name="breakdown" type="object">
  Score breakdown by category. Each field is an integer from 0 to 100.

  <ResponseField name="breakdown.discoverability" type="integer">
    Score for agent discoverability — manifest presence and validity.
  </ResponseField>

  <ResponseField name="breakdown.catalog" type="integer">
    Score for product catalog quality and structure.
  </ResponseField>

  <ResponseField name="breakdown.checkout" type="integer">
    Score for checkout endpoint availability and correctness.
  </ResponseField>

  <ResponseField name="breakdown.attribution" type="integer">
    Score for attribution snippet presence and configuration.
  </ResponseField>
</ResponseField>

<ResponseField name="passed" type="string[]">
  List of check IDs that passed with no issues.
</ResponseField>

***

## Severity reference

| Severity   | Meaning                                                   |
| ---------- | --------------------------------------------------------- |
| `critical` | Blocks agent discovery or checkout. Fix immediately.      |
| `high`     | Significantly reduces AI traffic or conversion. Fix soon. |
| `medium`   | Affects attribution or discoverability but not checkout.  |
| `low`      | Minor improvement opportunity.                            |

***

## Example request and response

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://asva-ai.com/api/audit \
    -H "Authorization: Bearer $ASVA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "domain": "yourstore.com"
    }'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch('https://asva-ai.com/api/audit', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ASVA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'yourstore.com' })
  })

  const audit = await response.json()
  console.log(`Score: ${audit.score} (${audit.grade})`)
  console.log('Critical gaps:', audit.gaps.filter(g => g.severity === 'critical'))
  ```

  ```python Python theme={null}
  import requests

  r = requests.post(
      'https://asva-ai.com/api/audit',
      headers={'Authorization': f'Bearer {ASVA_API_KEY}'},
      json={'domain': 'yourstore.com'}
  )
  audit = r.json()
  print(f"Score: {audit['score']} ({audit['grade']})")
  ```
</CodeGroup>

**Example response:**

```json theme={null}
{
  "domain": "yourstore.com",
  "score": 42,
  "grade": "C",
  "checked_at": "2026-04-10T11:00:00Z",
  "gaps": [
    {
      "id": "well_known_missing",
      "check": "well_known",
      "severity": "critical",
      "label": "/.well-known/ucp not found",
      "detail": "No response at https://yourstore.com/.well-known/ucp. Create this file to enable agent discovery.",
      "fix_url": "https://asva-ai.com/tools/manifest"
    },
    {
      "id": "product_schema_incomplete",
      "check": "schema",
      "severity": "high",
      "label": "Product JSON-LD schema missing on 6 pages",
      "detail": "Checked 10 product pages; 6 have no Product or Offer schema. AI systems cannot cite or price these products.",
      "fix_url": null
    },
    {
      "id": "dark_traffic_untracked",
      "check": "attribution",
      "severity": "medium",
      "label": "Asva attribution snippet not detected",
      "detail": "Install the Asva snippet to surface AI-sourced sessions in GA4.",
      "fix_url": "https://asva-ai.com/tools/readiness"
    }
  ],
  "breakdown": {
    "discoverability": 60,
    "catalog": 45,
    "checkout": 30,
    "attribution": 0
  },
  "passed": [
    "https_enabled",
    "feed_exists",
    "merchant_center_connected"
  ]
}
```

***

## Batch auditing

For agencies auditing multiple domains, loop through the API:

```bash theme={null}
#!/bin/bash
domains=("client1.com" "client2.com" "client3.com")

for domain in "${domains[@]}"; do
  result=$(curl -s -X POST https://asva-ai.com/api/audit \
    -H "Authorization: Bearer $ASVA_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"domain\": \"$domain\"}")

  score=$(echo $result | jq '.score')
  grade=$(echo $result | jq -r '.grade')
  echo "$domain: $score ($grade)"
done
```

<Note>
  The `/api/audit` endpoint allows 60 requests per hour. Space out batch jobs or use `dry_run: true` for subsequent calls against the same domain within the same session.
</Note>

***

## Related

* [Readiness Score tool](https://asva-ai.com/tools/readiness) — browser UI version of this API
* [Manifest API](/api-reference/manifest) — generate a manifest to fix `well_known_missing` gaps
* [UCP Implementation](/ucp/implementation) — fix UCP gaps step by step