API docs

Base URL: https://plaingrade-api.mike-tusa.workers.dev. JSON in, JSON out. English only.

POST /v1/score

Request body (JSON, at most 49,152 bytes):

curl -s https://plaingrade-api.mike-tusa.workers.dev/v1/score -H 'content-type: application/json' -H 'x-api-key: pg_…' \
  -d '{"text":"The Australian platypus is seemingly a hybrid of a mammal and reptilian creature.","lang":"en"}'

Response (the real response is compact JSON):

{
  "ok": true,
  "lang": "en",
  "scores": {
    "flesch_reading_ease": 24.4, "flesch_kincaid_grade": 13.1, "gunning_fog": 14.4, "smog": 14.6,
    "coleman_liau": 12.7, "ari": 9.7, "consensus_grade": 12.9
  },
  "interpretation": { "flesch_reading_ease": "Very difficult", "audience": "College graduate", "consensus_grade": "College" },
  "stats": {
    "characters": 81, "characters_no_spaces": 69, "letters": 68, "words": 13, "sentences": 1, "paragraphs": 1,
    "syllables": 26, "polysyllable_words": 4, "complex_words": 3, "avg_words_per_sentence": 13,
    "avg_syllables_per_word": 2, "avg_letters_per_word": 5.23, "reading_time_seconds": 3, "reading_time": "3 s",
    "speaking_time_seconds": 5
  },
  "long_sentences": { "threshold_words": 25, "count": 0, "items": [], "truncated": false },
  "notes": ["short_text: …", "smog_under_30_sentences: …"],
  "text_bytes": 81,
  "engine": "syllable@5.0.1 (+ small correction list) with in-house formulas and sentence splitter",
  "version": "0.3.1"
}

long_sentences.items holds up to 50 entries { index, start, end, words, text }: index is the sentence number (0-based), start/end are JavaScript string (UTF-16) offsets into your text (end exclusive), and text is the sentence, cut to 300 characters. scores and interpretation are null when the text has no words. notes can include short_text, smog_under_30_sentences, no_words and likely_not_english (most letters are not Latin script).

POST /v1/keys

Issues a free API key: 100 requests/day, 30/min, commercial use allowed. No email or sign-up needed. The key is shown once; we store only its SHA-256 hash. Up to 3 keys per IP per day (at most 2 per minute). Lost a key or need it revoked? Email digitalpromohub.support@gmail.com

curl -s -X POST https://plaingrade-api.mike-tusa.workers.dev/v1/keys -H 'content-type: application/json' -d '{}'

Send it as X-API-Key. GET /v1/usage with the header shows today's usage.

Limits and headers

• Without a key: 10 requests/min and 50/day per IP. With a free key: 30/min and 100/day.
• Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (daily quota, reset at 00:00 UTC, Unix seconds), X-RateLimit-Policy and X-API-Plan. A 429 includes Retry-After. CORS is open (Access-Control-Allow-Origin: *) on /v1/score.
• Body over 49,152 bytes (by Content-Length or by the bytes actually sent): 413 body_too_large. Text over 20,480 bytes: 413 text_too_large.
• There is also a service-wide daily soft cap. If it's reached, you get 429 daily_cap_reached until 00:00 UTC.

Errors

Errors look like {"ok":false,"error":{"code":"…","message":"…"}}. Codes: invalid_json, missing_text, invalid_lang, invalid_long_sentence_words (400); invalid_api_key, missing_api_key (401); cross_origin_forbidden (403); not_found (404); method_not_allowed (405); body_too_large, text_too_large (413); unsupported_media_type (415); unsupported_language (422); rate_limited, ip_daily_quota, key_quota_exceeded, issuer_quota_exceeded, key_issue_limit, daily_cap_reached (429); internal_error (500); not_configured, unavailable (503).

Other endpoints

GET /health returns the service status and version. GET /privacy is the privacy note.

How the scores are computed

• Sentences: our own splitter. It knows common abbreviations (Mr., Dr., e.g., i.e., U.S., a.m., etc.), decimals (3.14), ellipses, quotes ("Why?" she asked), Wikipedia-style citations ([1]), URLs and e-mail addresses. Each list/bullet item, heading and blank-line-separated paragraph is its own sentence; a single line break inside a paragraph is treated as a space.
• Words: runs of letters/digits, keeping apostrophes, hyphens and inner dots (don't, well-known, 3.14 and U.S. are one word each). A URL or e-mail address is one word of one syllable. Citation markers like [1] and bullet markers are not words.
• Syllables: the syllable library, per word part (well-known = well + known); a number counts as one syllable. Syllable counts come from a spelling-based heuristic, not a pronunciation dictionary. They are right for about 95% of common English words, so scores can differ by a few points from other tools (e.g. textstat, Hemingway) that count syllables differently.
• Letters (Coleman-Liau, ARI): letters and digits inside words.
• Complex words (Gunning Fog): 3+ syllables, excluding proper nouns (capitalised, not first in the sentence), hyphenated words, and words that reach 3 syllables only through -es, -ed or -ing. Polysyllables (SMOG): every word with 3+ syllables.
• Flesch Reading Ease = 206.835 − 1.015 × (words/sentences) − 84.6 × (syllables/words). Flesch-Kincaid grade = 0.39 × (words/sentences) + 11.8 × (syllables/words) − 15.59. Gunning Fog = 0.4 × (words/sentences + 100 × complex/words). SMOG = 1.043 × √(polysyllables × 30/sentences) + 3.1291. Coleman-Liau = 0.0588 × L − 0.296 × S − 15.8 (L = letters per 100 words, S = sentences per 100 words). ARI = 4.71 × (letters/words) + 0.5 × (words/sentences) − 21.43. Consensus grade = the mean of the five grade-level scores.
• Scores are not clamped: Flesch Reading Ease can go below 0 or above 100, and grades can be negative for very simple text. Reading time assumes 238 words/minute; speaking time 150 words/minute.
• English only. Scores are unstable under ~100 words, and SMOG was designed for 30+ sentences; the response flags both in notes.

Support

Questions, key revocation or abuse reports: digitalpromohub.support@gmail.com.

Pricing

Paid tiers are not available yet.