POST /v1/read-and-score

Markdown + AIO score + hallucination risk in one request.

◈

Path note: the PRD originally called this /v1/read+score, but the literal + URL-decodes to a space in many HTTP clients, so the canonical path is /v1/read-and-score.

When to use it

Use this when you need both the clean Markdown and the AIO score in a single call — typical for agents that want to decide whether to trust a page before feeding it to the LLM. Costs the same as one Read or Score call (single quota debit). Cached for 1 hour just like /v1/read.

Endpoint

http

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

Request body matches /v1/read:

urlstringrequiredPublic URL to fetch + clean + score.

freshbooleanoptionalBypass the 1-hour cache.

Response

A union of the /v1/read response and the /v1/score response.

json

{
  "status": "success",
  "url": "https://stripe.com",
  "markdown": "# Stripe — Online payments…",
  "metadata": { "title": "...", "description": "...", "language": "en" },

  "aio_score": 92,
  "grade": "Excellent",
  "hallucination_risk": "low",

  "insights": { "has_jsonld": true, "headings_ok": true, "..." : "..." },
  "penalties": [ "Missing canonical link tag" ],
  "benefits":  [ "Clean semantic HTML", "JSON-LD present" ],
  "recommendations": [ { "priority": "Low", "title": "...", "description": "..." } ],

  "stats": {
    "raw_html_size_kb": 605.0,
    "markdown_size_kb": 14.8,
    "reduction_percent": 97.6,
    "extraction_time_ms": 412
  },
  "cache": { "hit": false, "ttl_seconds": 3600 }
}

Example

bash

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