README health score API

0–100 score across 5 weighted sections.

POST /api/v1/audit/readme-score gives a README a 0–100 health score across heading hierarchy, GFM compliance, image alt text, link integrity, and open tasks. Returns a grade and an actionable issue list.

Overview

Composite health score for a README (or any markdown doc), combining heading hierarchy, GFM compliance, image alt text, link integrity, and open task ratio. Returns a 0–100 score, a letter grade, per-section breakdown, and an actionable issue list.

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/audit/readme-score' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"markdown":"# Project\n\n## Intro\n\nHi."}'

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": {
    "score": 82,
    "grade": "B",
    "sections": [
      {
        "id": "headings",
        "label": "Heading hierarchy",
        "passed": 1,
        "total": 1,
        "weight": 20,
        "detail": "Outline is consistent."
      }
    ],
    "issues": []
  }
}

Use cases

Repo dashboards

Show a 'README quality' badge across every repo in an org.

Pre-publish gating

Block merges when score drops below a threshold.

Try in browser

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

README Health Score
0–100 quality grade

Try it

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