API reference

The AISO API is a free, unauthenticated REST surface for programmatically scanning URLs against eight deterministic AI-visibility dimensions and four real LLM engines. Every endpoint is JSON-in, JSON-out with one exception (the badge, which returns SVG, and the PDF, which returns application/pdf).

Base URL and rate limits

Base URL: https://aiso.tools

• 3 scans per IP per 24h. Exceeding returns 429 rate_limited_ip.
• 10 scans per domain per 24h. Exceeding returns 429 rate_limited_domain.
• 24h URL dedupe cache. Repeat scans of the same URL within 24 hours return a fresh scanId but reuse the existing deterministic + LLM results (zero LLM spend).

POST /api/scan

Queue a scan. Returns immediately; scan runs in the background.

curl -X POST https://aiso.tools/api/scan \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com"}'

Response (200):

{
  "scanId": "b3c8e2a1-...-...",
  "status": "queued"
}

GET /api/scan/:id

Fetch the full payload for a scan.

curl https://aiso.tools/api/scan/b3c8e2a1-...

Response shape:

{
  "scanId": "...",
  "url": "https://example.com",
  "status": "completed",          // queued | running | completed | failed
  "score": 72,                     // 0-100 or null
  "tier": "visible",               // invisible | partial | visible | cited
  "runtimeVisibility": 55,         // 0-100 or null
  "enginesUsed": ["anthropic", "openai"],
  "scanCostCents": 4,
  "dimensions": [
    {
      "key": "crawler",
      "label": "Crawler Access",
      "weight": 15,
      "score": 15,
      "status": "pass",
      "issues_count": 0
    }
  ],
  "issues": [
    {
      "severity": "critical",
      "title": "No /llms.txt file found",
      "fix": "Publish /llms.txt at the site root...",
      "auto_fixable": true,
      "dimension_key": "llmstxt"
    }
  ],
  "promptTests": [
    {
      "engine": "anthropic",
      "prompt": "best customer support automation for SaaS",
      "cited": true,
      "position": 2,
      "brandMentioned": true,
      "snippet": "..."
    }
  ]
}

Poll this endpoint every 2 seconds while status is queued or running. Typical p50 end-to-end is under 30 seconds; p95 is around 60 seconds when all four LLM engines are configured.

GET /api/badge/:domain

Returns an SVG score badge for the most recently completed scan of a domain. Auto-updates as scans arrive. Cache: 24h public.

curl https://aiso.tools/api/badge/agntdot.com

Embed in a README or landing page:

<a href="https://aiso.tools/scan/<id>">
  <img src="https://aiso.tools/api/badge/agntdot.com" alt="AISO Score">
</a>

GET /api/scan/:id/pdf

Returns the scan as a downloadable, 4-page application/pdf. No auth, no email gate. Generated on-demand; ~3s latency.

curl -LO https://aiso.tools/api/scan/b3c8e2a1-.../pdf

GET /api/scan/:id/og

Returns the 1200×630 social-share preview PNG for a scan. Embedded automatically via the scan page's Open Graph tags — you probably don't need to call this directly unless you're building a custom preview.

Error shapes

Every error response follows:

{
  "error": "error_code",
  "message": "Human-readable description",
  "retryAfterSeconds": 86400   // only on 429
}

Possible error codes:

• invalid_url — URL failed Zod validation or is not http/https.
• rate_limited_ip / rate_limited_domain — over the 24h cap. Read retryAfterSeconds.
• invalid_id — scanId is not a valid UUID.
• not_found — scanId does not exist.
• scan_failed — the scan transitioned to failed; check errorMessage on the returned scan object.