Readability Score Document Api

What it does

Readability Score scores the readability of plain text, uploaded documents, and web pages. Send it raw text, a public URL, a public document URL, or a file upload, and get back word, sentence, character, and paragraph counts plus estimated reading and speaking time.

Use language to choose the scoring model: english returns Flesch-Kincaid Reading Ease, while german returns Wiener Sachtextformel. For each analysis, the response includes stats and a readability result object with class, label, level, score, and class_label, so you can compare content quality against a clear threshold and grade-level style label.

This is useful when you need to check whether product copy, support articles, policy pages, or marketing content is easy to read before publishing. It also fits content pipelines that automate editorial QA, accessibility checks, or internal review for long-form documents.

Readability Score works with PDF, DOC, and DOCX files, plus publicly accessible web pages and document URLs. Keep the input type aligned with the endpoint you call, and use the output to spot overly dense paragraphs, long sentences, or text that falls outside your target reading level.

▣ ENDPOINT 01 / 02

POST

Score readability of an uploaded document

https://api.eu.apyverse.com/apyhub/score-readability/file

QUICKSTART

GUIDE

Quickstart

Upload a document to analyze its readability.

curl -X POST "https://api.eu.apyverse.com/apyhub/score-readability/file" \
  -H "apy-token: $APY_TOKEN" \
  -F "file=@/path/to/document.pdf"

What you'll get back

Returns a JSON object with a data object. The data object includes stats with document counts and timing metrics, plus one readability result object: for this endpoint, flesh_kincaid_reading_ease.

{
  "data": {
    "stats": {
      "words": 95,
      "sentences": 8,
      "characters": 512,
      "paragraphs": 2,
      "reading_time": 6.49,
      "speaking_time": 38,
      "avg_word_length": 5.39,
      "avg_sentence_length": 11.88,
      "avg_paragraph_length": 4
    },
    "flesh_kincaid_reading_ease": {
      "class": "8th & 9th grade",
      "label": false,
      "level": 6.49,
      "score": 65.74,
      "class_label": "Plain English. Easily understood by 13- to 15-year-old students."
    }
  }
}

TRY ITLIVE · 250 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

About this endpoint

What it does

Uploads a document file and returns readability statistics for the extracted text. The request body includes the file to analyse and an optional language selector; the response wraps the computed metrics under a data object.

Request Body

Parameter	Type	Mandatory	Description
file	String	Yes	Document file to analyse. Supported formats: PDF, DOC, or DOCX.
language	ENUM	No	Language used for analysis. Allowed values: `english`, `german`. Default: `english`.

Response

Returns a JSON object with a data object field. The data object contains stats plus one readability result object: flesh_kincaid_reading_ease or wiener_sachtextformel, depending on the response variant.

Parameter	Type	Mandatory	Description
data	Object	Yes	Wrapper for the readability analysis result. Contains `stats` and one readability metric object.
data.stats	Object	Yes	Aggregated text statistics.
data.stats.words	Integer	No	Number of words.
data.stats.sentences	Integer	No	Number of sentences.
data.stats.characters	Integer	No	Number of characters.
data.stats.paragraphs	Integer	No	Number of paragraphs.
data.stats.reading_time	Number	No	Estimated reading time in seconds.
data.stats.speaking_time	Number	No	Estimated speaking time in seconds.
data.stats.avg_word_length	Number	No	Average word length.
data.stats.avg_sentence_length	Number	No	Average sentence length.
data.stats.avg_paragraph_length	Number	No	Average paragraph length.
data.flesh_kincaid_reading_ease	Object	No	Readability result object for the Flesh-Kincaid Reading Ease variant. Contains `class`, `label`, `level`, `score`, and `class_label`.
data.flesh_kincaid_reading_ease.class	String	No	Readability class label.
data.flesh_kincaid_reading_ease.label	Object	No	Whether the text meets a standard readability threshold.
data.flesh_kincaid_reading_ease.level	Number	No	Readability level.
data.flesh_kincaid_reading_ease.score	Number	No	Readability score.
data.flesh_kincaid_reading_ease.class_label	String	No	Human-readable description of the readability class.
data.wiener_sachtextformel	Object	No	Readability result object for the Wiener Sachtextformel variant. Contains `class`, `label`, `level`, `score`, and `class_label`.
data.wiener_sachtextformel.class	String	No	Readability class label.
data.wiener_sachtextformel.label	Object	No	Whether the text meets a standard readability threshold.
data.wiener_sachtextformel.level	Number	No	Readability level.
data.wiener_sachtextformel.score	Number	No	Readability score.
data.wiener_sachtextformel.class_label	String	No	Human-readable description of the readability class.

Body

Name

Type

Description

bodyREQUIRED

object

—

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

▣ ENDPOINT 02 / 02

POST

Score readability of a web page

https://api.eu.apyverse.com/apyhub/score-readability/url

QUICKSTART

GUIDE

Quickstart

Send a webpage URL to score its readability.

curl -X POST "https://api.eu.apyverse.com/apyhub/score-readability/url" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"file_url":"https://assets.apyhub.com/samples/sample.html"}'

What you'll get back

Returns a JSON object with a data object. Inside data, stats contains readability metrics like words, sentences, characters, paragraphs, reading_time, speaking_time, avg_word_length, avg_sentence_length, and avg_paragraph_length, and flesh_kincaid_reading_ease contains the score details.

{
  "data": {
    "stats": {
      "words": 95,
      "sentences": 8,
      "characters": 512,
      "paragraphs": 2,
      "reading_time": 6.49,
      "speaking_time": 38,
      "avg_word_length": 5.39,
      "avg_sentence_length": 11.88,
      "avg_paragraph_length": 4
    },
    "flesh_kincaid_reading_ease": {
      "class": "8th & 9th grade",
      "label": false,
      "level": 6.49,
      "score": 65.74,
      "class_label": "Plain English. Easily understood by 13- to 15-year-old students."
    }
  }
}

TRY ITLIVE · 250 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Scores the readability of a publicly accessible web page URL and returns readability statistics plus one readability model result. The request body must include url; language is optional and defaults to english.

Request Body

Parameter	Type	Mandatory	Description
file_url	String	Yes	Publicly accessible web page URL. Must be a URI.
language	ENUM	No	Language used for scoring. Allowed values: `english`, `german`. Default: `english`.

Response

Returns a JSON object with a data object field. Inside data, the response includes a stats object for text metrics and one readability result object: either flesh_kincaid_reading_ease or wiener_sachtextformel, depending on which schema variant is returned.

Parameter	Type	Mandatory	Description
data	Object	Yes	Wrapper object for the readability result.
data.stats	Object	Yes	Text statistics for the page.
data.stats.words	Integer	Yes	Number of words.
data.stats.sentences	Integer	Yes	Number of sentences.
data.stats.characters	Integer	Yes	Number of characters.
data.stats.paragraphs	Integer	Yes	Number of paragraphs.
data.stats.reading_time	Number	Yes	Estimated reading time in seconds.
data.stats.speaking_time	Number	Yes	Estimated speaking time in seconds.
data.stats.avg_word_length	Number	Yes	Average word length.
data.stats.avg_sentence_length	Number	Yes	Average sentence length.
data.stats.avg_paragraph_length	Number	Yes	Average paragraph length.
data.flesh_kincaid_reading_ease	Object	Yes (in one schema variant)	Readability result object for the Flesh Kincaid Reading Ease variant. Contains `class`, `label`, `level`, `score`, and `class_label`.
data.wiener_sachtextformel	Object	Yes (in one schema variant)	Readability result object for the Wiener Sachtextformel variant. Contains `class`, `label`, `level`, `score`, and `class_label`.

Notes

The response schema is a oneOf with two variants. In both variants, data.stats is present, but the second top-level readability object differs: one variant returns data.flesh_kincaid_reading_ease, while the other returns data.wiener_sachtextformel.

Body

Name

Type

Description

bodyREQUIRED

object

—

▣ 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.