apyhub
Back
▣ MEDIA KIT

Analyze Webpage AI Readability API

What it does

AI Readability Score checks how suitable a web page is for AI systems to read and use. Send a URL in the url query parameter and get a readability assessment back for that page.

Use it when you want to know whether a page is likely to be easy for models, crawlers, or downstream automation to process. That can help you audit content before exposing it to assistants, compare pages in a site migration, or spot pages that may need structural changes before they are used in retrieval workflows.

It has one endpoint, AI readability score for one URL.

If you are building tools that depend on machine-readable web content, this gives you a quick check on whether a page is a good candidate for AI consumption.

The JSON response carries the AI readability score and grade, four category scores and recommendations.

GET
AI readability score for one URL
https://api.eu.apyhub.com/seoscoreapi/analyze-webpage-ai-readability

QUICKSTART

GUIDE

Quickstart

Check a page’s URL for AI readability by passing it as a query parameter.

curl -X GET "https://api.eu.apyhub.com/seoscoreapi/analyze-webpage-ai-readability?url=https%3A%2F%2Fwww.wikipedia.org" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

A real response to the request above, with every array cut to its first 2 items:

{
  "url": "https://www.wikipedia.org",
  "ai_readability_score": 60,
  "ai_readability_grade": "C",
  "categories": {
    "crawl_accessibility": {
      "score": 18,
      "max": 25,
      "checks": [
        {
          "name": "ssr_content",
          "status": "pass",
          "score": 8,
          "max": 8,
          "detail": "Server-rendered content detected"
        },
        {
          "name": "ai_bot_access",
          "status": "pass",
          "score": 5,
          "max": 5,
          "detail": "All major AI bots allowed"
        }
      ]
    },
    "structural_markup": {
      "score": 11,
      "max": 25,
      "checks": [
        {
          "name": "schema_jsonld",
          "status": "warning",
          "score": 0,
          "max": 8,
          "detail": "No valid JSON-LD structured data"
        },
        {
          "name": "semantic_html",
          "status": "warning",
          "score": 2,
          "max": 5,
          "detail": "5 semantic elements, 112 divs (4% ratio)"
        }
      ]
    },
    "content_extractability": {
      "score": 22,
      "max": 30,
      "checks": [
        {
          "name": "answer_first",
          "status": "pass",
          "score": 5,
          "max": 6,
          "detail": "5/6 sections lead with facts"
        },
        {
          "name": "chunk_friendly",
          "status": "warning",
          "score": 3,
          "max": 6,
          "detail": "3/6 — sections sized for RAG chunking"
        }
      ]
    },
    "ai_discoverability": {
      "score": 9,
      "max": 20,
      "checks": [
        {
          "name": "open_graph",
          "status": "pass",
          "score": 4,
          "max": 4,
          "detail": "5/5 OG tags present"
        },
        {
          "name": "semantic_urls",
          "status": "pass",
          "score": 3,
          "max": 3,
          "detail": "/"
        }
      ]
    }
  },
  "recommendations": [
    {
      "severity": "high",
      "issue": "No Schema.org JSON-LD structured data",
      "fix": "Add JSON-LD markup (Article, WebPage, FAQPage, etc.) so AI systems can understand your content type and metadata",
      "plain_english": "The page has no machine-readable labels, so it can't earn rich results (stars, prices, FAQs) in search.",
      "who_fixes_it": "developer"
    },
    {
      "severity": "medium",
      "issue": "No canonical URL set",
      "fix": "Add a canonical tag to help AI systems identify the primary version of this page",
      "plain_english": "The page doesn't say which address is the official one, so search engines may split its ranking across duplicates.",
      "who_fixes_it": "developer"
    }
  ]
}
TRY ITLIVE · 150 ATOMS
Loading your default key…
The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.
The page to analyse, as a full URL including `https://`.

About this endpoint

What it does

Scores how easily AI models and assistants can read, extract and cite a page: crawl access for AI bots, structural markup, content extractability and AI discoverability (llms.txt, structured data). Returns a score and recommendations.

Query Parameter(s)

AttributeTypeMandatoryDescription
urlStringYesThe URL to analyze for AI readability

Response

A JSON object; nested fields are written parent.child, and [] marks an array of objects.

FieldTypeDescription
urlstringThe URL that was checked, as you sent it.
categoriesobjectScore per category; each has its checks.
categories.structural_markupobjectDoes markup describe the content: headings, semantic HTML, structured data.
categories.structural_markup.maxintegerMost points this category can earn.
categories.structural_markup.scoreintegerCategory score, 0–100.
categories.structural_markup.checksarray of objectIndividual checks behind this category's score.
categories.structural_markup.checks[].namestringMachine name of the check (e.g. title, meta_description, h1).
categories.structural_markup.checks[].statusstringResult of the check — pass, warning, fail or info (informational, not scored).
categories.structural_markup.checks[].scoreintegerPoints this check earned (0–100 for audit checks; out of max where max is given).
categories.structural_markup.checks[].maxintegerMost points this check can earn.
categories.structural_markup.checks[].detailstringWhat the check found, in one line.
categories.ai_discoverabilityobjectCan AI tools find and cite the page: metadata, canonical, sitemap, freshness.
categories.ai_discoverability.maxintegerMost points this category can earn.
categories.ai_discoverability.scoreintegerCategory score, 0–100.
categories.ai_discoverability.checksarray of objectIndividual checks behind this category's score.
categories.ai_discoverability.checks[].namestringMachine name of the check (e.g. title, meta_description, h1).
categories.ai_discoverability.checks[].statusstringResult of the check — pass, warning, fail or info (informational, not scored).
categories.ai_discoverability.checks[].scoreintegerPoints this check earned (0–100 for audit checks; out of max where max is given).
categories.ai_discoverability.checks[].maxintegerMost points this check can earn.
categories.ai_discoverability.checks[].detailstringWhat the check found, in one line.
categories.crawl_accessibilityobjectCan AI crawlers fetch the page: server-rendered text, bot access, llms.txt, HTTPS, speed.
categories.crawl_accessibility.maxintegerMost points this category can earn.
categories.crawl_accessibility.scoreintegerCategory score, 0–100.
categories.crawl_accessibility.checksarray of objectIndividual checks behind this category's score.
categories.crawl_accessibility.checks[].namestringMachine name of the check (e.g. title, meta_description, h1).
categories.crawl_accessibility.checks[].statusstringResult of the check — pass, warning, fail or info (informational, not scored).
categories.crawl_accessibility.checks[].scoreintegerPoints this check earned (0–100 for audit checks; out of max where max is given).
categories.crawl_accessibility.checks[].maxintegerMost points this check can earn.
categories.crawl_accessibility.checks[].detailstringWhat the check found, in one line.
categories.content_extractabilityobjectCan the main content be pulled out cleanly: text structure, readability, lists and tables.
categories.content_extractability.maxintegerMost points this category can earn.
categories.content_extractability.scoreintegerCategory score, 0–100.
categories.content_extractability.checksarray of objectIndividual checks behind this category's score.
categories.content_extractability.checks[].namestringMachine name of the check (e.g. title, meta_description, h1).
categories.content_extractability.checks[].statusstringResult of the check — pass, warning, fail or info (informational, not scored).
categories.content_extractability.checks[].scoreintegerPoints this check earned (0–100 for audit checks; out of max where max is given).
categories.content_extractability.checks[].maxintegerMost points this check can earn.
categories.content_extractability.checks[].detailstringWhat the check found, in one line.
recommendationsarray of objectFix list, most important first.
recommendations[].severitystringHow much fixing it matters — high, medium or low.
recommendations[].issuestringThe problem found, in a short phrase.
recommendations[].fixstringThe change to make.
recommendations[].plain_englishstringWhy it matters, in plain language for a non-specialist.
recommendations[].who_fixes_itstringWho usually makes the fix — e.g. content (copywriter/editor), developer, marketing.
ai_readability_gradestringAI readability letter grade, A+ to F.
ai_readability_scoreintegerAI readability score, 0–100.
▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.