ReadResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/buildonto-dev/json-schema/buildonto-dev-read-response-schema.json",
  "title": "ReadResponse",
  "x-generated": "2026-11-03",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/buildonto-dev-openapi.yaml#/components/schemas/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"
    }
  },
  "$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."
        }
      }
    },
    "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"
        }
      }
    }
  }
}