POST /v1/score

Score any URL for AI readability — get penalties, benefits, and ranked recommendations.

Through the API, every page without the Onto SDK takes the −10 Unmanaged AI Payload penalty, so scores top out at 90 without the SDK.

POST https://api.buildonto.dev/v1/score
Authorization: Bearer onto_sk_live_YOUR_KEY
Content-Type: application/json

{
  "status": "success",
  "url": "https://stripe.com",
  "aio_score": 90,
  "grade": "Excellent",
  "hallucination_risk": "low",
  "insights": {
    "robots_allowed": true,
    "waf_blocked": false,
    "markdown_supported": true,
    "json_ld_present": true,
    "semantic_hierarchy": true
  },
  "penalties": [
    "Warning: Unmanaged AI Payload. Native Markdown is present but lacks Onto-specific brand controls, versioning, and agent analytics."
  ],
  "benefits": [
    "Native Markdown Support: This site natively serves Markdown to agents, which improves extraction but lacks the Onto-optimized management layer.",
    "Payload Optimization: Native Markdown reduced the agent payload to 14.8KB, eliminating ~98% of visual noise."
  ],
  "recommendations": [
    {
      "priority": "Medium",
      "title": "Migrate to Onto SDK",
      "description": "Native Markdown detected but lacks agent analytics and policy controls. Upgrade to the Onto layer."
    }
  ],
  "stats": { "raw_size": "605KB", "efficiency": "97.6%", "extraction_time_ms": 412 },
  "bot_preview": "# Stripe — Online payments…\n\n…"
}

penalties, benefits and recommendations are drawn from a fixed set of scorer strings — they are not free-form. Note that benefits describes what the Onto layer contributes, so some entries appear precisely because the page is missing something (the JSON-LD benefit, for instance, is emitted only when no JSON-LD is found). insights always carries exactly these five booleans.

/v1/score has no cache layer, so — unlike /v1/read-and-score — it does not send X-Onto-Cache. It never bills credits, so it never sends X-Credits-Remaining.

Because it costs 0 credits, RATE_LIMITED and PAYMENT_REQUIRED cannot happen here. CONCURRENT_LIMIT can. The robots.txt override for domains you own does not apply on this endpoint, so a site that blocks Onto returns ROBOTS_BLOCKED even if you own it. See error codes.

hallucination_risk is computed from the score and the insights, not from the grade band — a grade does not map to a fixed risk. It is high if robots.txt disallows AI agents, or the score is under 50, or the page has neither JSON-LD nor a semantic heading hierarchy; medium if the score is under 80, or any of markdown_supported, json_ld_present or semantic_hierarchy is false; and low otherwise.

curl -X POST https://api.buildonto.dev/v1/score \
  -H "Authorization: Bearer $ONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://stripe.com"}'