ReadAndScoreResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/buildonto-dev/json-schema/buildonto-dev-read-and-score-response-schema.json",
  "title": "ReadAndScoreResponse",
  "x-generated": "2026-11-03",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/buildonto-dev-openapi.yaml#/components/schemas/ReadAndScoreResponse",
  "allOf": [
    {
      "$ref": "#/$defs/ReadResponse"
    },
    {
      "type": "object",
      "required": [
        "aio_score",
        "grade",
        "hallucination_risk",
        "insights",
        "penalties",
        "benefits",
        "recommendations"
      ],
      "properties": {
        "aio_score": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "maximum": 100,
          "description": "Null for PDF and plain-text URLs."
        },
        "grade": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "Excellent",
            "Good",
            "Needs work",
            "AI-hostile",
            "Invisible",
            null
          ]
        },
        "hallucination_risk": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "low",
            "medium",
            "high",
            null
          ]
        },
        "insights": {
          "$ref": "#/$defs/ScoringInsights"
        },
        "penalties": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "benefits": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "recommendations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Recommendation"
          }
        }
      }
    }
  ],
  "$defs": {
    "CacheInfo": {
      "type": "object",
      "required": [
        "hit",
        "ttl_seconds"
      ],
      "properties": {
        "hit": {
          "type": "boolean"
        },
        "ttl_seconds": {
          "type": "integer",
          "description": "Cache TTL applied to this response (currently 3600)."
        }
      }
    },
    "Metadata": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "language": {
          "type": "string",
          "description": "ISO 639-1 language code if detected."
        }
      }
    },
    "ReadResponse": {
      "type": "object",
      "required": [
        "status",
        "url",
        "markdown",
        "metadata",
        "stats",
        "cache"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "success"
          ]
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "markdown": {
          "type": "string",
          "description": "Clean, agent-ready Markdown extracted from the target URL."
        },
        "metadata": {
          "$ref": "#/$defs/Metadata"
        },
        "stats": {
          "$ref": "#/$defs/ReadStats"
        },
        "warnings": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Sent by `/v1/read` only when there is something to flag — for example, a page that\nyielded very little text and most likely renders its content with JavaScript, which\nOnto does not execute.\n"
        },
        "cache": {
          "$ref": "#/$defs/CacheInfo"
        }
      }
    },
    "ReadStats": {
      "type": "object",
      "required": [
        "raw_html_size_kb",
        "markdown_size_kb",
        "reduction_percent",
        "extraction_time_ms"
      ],
      "properties": {
        "raw_html_size_kb": {
          "type": "number"
        },
        "markdown_size_kb": {
          "type": "number"
        },
        "reduction_percent": {
          "type": "number",
          "description": "How much smaller the Markdown is vs. the raw HTML (0–100)."
        },
        "extraction_time_ms": {
          "type": "integer"
        }
      }
    },
    "Recommendation": {
      "type": "object",
      "required": [
        "title",
        "description",
        "priority"
      ],
      "properties": {
        "title": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "priority": {
          "type": "string",
          "enum": [
            "High",
            "Medium",
            "Low"
          ]
        }
      }
    },
    "ScoringInsights": {
      "type": "object",
      "required": [
        "robots_allowed",
        "waf_blocked",
        "markdown_supported",
        "json_ld_present",
        "semantic_hierarchy"
      ],
      "properties": {
        "robots_allowed": {
          "type": "boolean"
        },
        "waf_blocked": {
          "type": "boolean"
        },
        "markdown_supported": {
          "type": "boolean"
        },
        "json_ld_present": {
          "type": "boolean"
        },
        "semantic_hierarchy": {
          "type": "boolean"
        }
      }
    }
  }
}