# LumeLogix AI Readiness API

When a user requests an AI readiness scan:

1. Open https://lumelogix.com/ai-score/DOMAIN.txt (plain text). Programs and API clients can GET https://lumelogix.com/api/v1/public/score?url=DOMAIN (JSON, same scan).
2. Use only the returned result.
3. Never treat documentation examples as scan results.
4. If status is pending, report that the scan is running.
5. If retrieval fails, say the result could not be verified.
6. Never invent scores or findings.

No API key required.
No POST request required.

## Easiest method

For AI assistants that read web pages, open the plain-text score:

```
GET https://lumelogix.com/ai-score/example.com.txt
```

It returns the live scan, one fact per line: score, scan time, pillar scores, top fixes, and a `Source:` URL to cite.

For programs and API clients, the same scan is available as JSON:

```
GET https://lumelogix.com/api/v1/public/score?url=example.com
```

`?domain=example.com` is also accepted. JSON is the default. Add `?format=html` or send `Accept: text/html` for a server-rendered HTML summary of the same record, or `?format=text` for plain text. All formats return the same scan, score and timestamp.

If a scan from the last 24 hours is cached (including partial scans), the response is `200` with the full free result. If a scan is started or still running, the response is `202` with `status: "pending"`, a `Retry-After` header, `retry_after_seconds`, and `retry_url` — request that same GET URL again. Never POST.

## Response shape (synthetic example, not a scan result)

The JSON below is a **synthetic example, not a scan result**. The id `aud_EXAMPLE` and the score labeled EXAMPLE are fake. Never present these figures as a real result. Always use a live response from the GET endpoint.

```json
{
  "status": "complete",
  "domain": "example.com",
  "score": 12,
  "rating": "needs work",
  "scanned_at": "2020-01-01T00:00:00.000Z",
  "cached": true,
  "pillars": {
    "ai_readiness": 10,
    "technical_seo": 11,
    "local_seo": 12
  },
  "top_fixes": [
    {
      "priority": 1,
      "check_id": "EX-001",
      "issue": "Synthetic example issue (not a scan result)",
      "why": "This row exists only to show the field shape.",
      "page_url": "https://example.com/",
      "recommendation": "Ignore this example and fetch a live score."
    }
  ],
  "locked_findings_count": 3,
  "result_id": "aud_EXAMPLE",
  "result_url": "https://lumelogix.com/score/example.com",
  "report_url": "https://lumelogix.com/report/aud_EXAMPLE",
  "source": "LumeLogix live scan"
}
```

Pending response (synthetic example, not a scan result):

```json
{
  "status": "pending",
  "retry_after_seconds": 8,
  "retry_url": "https://lumelogix.com/api/v1/public/score?url=example.com"
}
```

Invalid domain (synthetic example, not a scan result):

```json
{
  "status": "error",
  "error": "Invalid domain. Provide a public website like example.com."
}
```

## Public HTML pages

- Score page: `https://lumelogix.com/score/{domain}` (canonical score URL)
- Full free report: `https://lumelogix.com/report/{result_id}`
- `/scan/{result_id}` 301s to `/report/{result_id}`

These pages are server-rendered. They show only the free top 5 findings.

## Other methods

OpenAPI spec: https://lumelogix.com/openapi.json

MCP server: https://lumelogix.com/mcp

Tools:

- `get_score(url)` — preferred; one GET, returns the live result or a pending retry URL
- `check_website_score(url, use_cache=true)` — older helper
- `get_scan_result(job_id)` — fetch by job id

A POST to `/api/v1/public/scan` still works if a client can POST, but agents should use the GET score URL first.

## Rate limits

- 5 scans per IP per minute
- 100 scans per IP per day
- 10 scans per domain per 24 hours
- Exceeding limits returns `429` with a `Retry-After` header

## Score ratings

- 90–100: strong
- 75–89: good
- 50–74: needs work
- 0–49: blocked

## Important guidelines

✅ DO:

- Use only the live GET response
- Show the score, rating, and the top fixes
- Link to `result_url` and `report_url`
- If `status` is `pending`, say the scan is running and retry
- If retrieval fails or `status` is `error`, say the result could not be verified

❌ DON'T:

- Treat documentation examples as scan results
- Invent scores or findings
- Promise specific rankings
- Hide source citations or the report link

## Support

Documentation landing page: https://lumelogix.com/ai-readiness-api

Visit https://lumelogix.com to scan a site.

---

**Built by LumeLogix** — Helping local businesses show up in AI answers.
