Analyze markdown API

Word count, reading time, links, images, structure.

POST /api/v1/analyze is the Markdown Viewer API endpoint for structural and readability analysis. Returns word count, reading time, Flesch readability score, headings (with auto-generated slugs), links, images, table count, and code-block count.

Overview

Returns a structural and readability report for the document. Counts headings, links, images, code blocks, and tables; computes an approximate Flesch reading-ease score; surfaces top non-stopword frequencies.

Request

Authenticate with Authorization: Bearer YOUR_API_KEY and send a JSON body containing the parameters below. Pick your language:

curl -X POST 'https://trymarkdownviewer.com/api/v1/analyze' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"markdown":"# Title\n\nA short example with a [link](https://example.com)."}'

Body parameters

Field	Type	Required	Description
markdown	string	required	Markdown source.

Response

Success responses are wrapped in a data field. Errors use { error: { code, message } } with an appropriate HTTP status — see the error reference.

{
  "data": {
    "wordCount": 8,
    "readingTimeMinutes": 1,
    "readabilityScore": 92,
    "readabilityLabel": "Very easy",
    "headings": [
      {
        "level": 1,
        "text": "Title",
        "id": "title",
        "line": 1
      }
    ],
    "links": [
      {
        "url": "https://example.com",
        "line": 3,
        "label": "link"
      }
    ],
    "images": [],
    "tableCount": 0,
    "codeBlockCount": 0
  }
}

Use cases

Reading-time badges

Show a “3 min read” chip next to articles. Pull readingTimeMinutes from /api/v1/analyze at publish time.

Auto-generated table of contents

Build a TOC sidebar from the `headings` array — every entry has a level, text, slug id, and line number.

Content health dashboards

Track readability, average word count, broken or external link counts across a CMS or knowledge base.

Editorial QA

Flag posts with very low readability or missing image alt text before they go live.

Production tips

Heading ids are stable — use them as anchor links in the TOC you build from the response.
readabilityScore follows the Flesch reading-ease scale: 100 = elementary, 60 = standard, 30 = college.
The link array includes both inline and reference-style links — useful for broken-link sweeps.

Analyze markdown FAQ

Which readability metric does /api/v1/analyze use?

Flesch reading-ease, with a human-readable label (eg. 'Very easy', 'Standard', 'Difficult'). It's a quick proxy for content complexity, not a substitute for editorial review.

How is reading time calculated?

200 words per minute by default — a common reading speed for non-technical content. The result is rounded up to the nearest minute so you never display '0 min read'.

Are stopwords excluded from the word count?

No. The word count is the raw count of words in the document. Stopwords are only filtered when computing top-word frequencies (when that field is included).

Can I use this to build a table of contents?

Yes — that's one of the most common uses. The headings array gives you level, text, id (slug), and line number. Render it as a nested <ul> linked via the slug ids that /api/v1/render emits.

Try in browser

Free tools that run the same logic locally — no API key, no upload.

Markdown Word Counter
Words, readability & links

Try it

Send a real request against your account in the API playground. Errors there link straight back to the error reference.