API
Start a scan, poll until it is done, read the grade and every finding as JSON. Free, with or without a key.
Limits
- No key: 5 scans per day per IP address, up to 300 pages per scan.
- With an API key (free, needs an account): 20 scans per day, up to 500 pages per scan.
- Results for the same address are reused for 24 hours; add
"fresh": trueto scan again.
1. Start a scan
curl -X POST https://infoharness.com/api/scans \
-H "Authorization: Bearer ih_your_key" \
-H "Content-Type: application/json" \
-d '{"url": "https://docs.example.com"}'
Returns {"id": "…", "cached": false, "report_url": "/r/…"}. The Authorization header is optional.
2. Poll until it is done
curl https://infoharness.com/api/scans/ID
status is queued, running, done or failed. While it runs, progress (0 to 100), pages_crawled and a live object show where it is. Poll every 2 to 5 seconds.
3. Read the result
When status is done the response includes grade (A to F), score (0 to 100), summary and issues: a list of findings, each with type, severity, title, page_a, page_b, quotes and extra details.
{"status": "done", "grade": "B", "score": 86.0,
"summary": {"total_issues": 14, "by_type": {"stale": 9, "broken_link": 5}},
"issues": [{"type": "broken_link", "severity": "medium", "title": "Broken internal link (HTTP 404)", ...}]}
Other endpoints
GET /r/ID/export.csv: findings as CSV.GET /badge/ID.svg: a docs health badge for your README.GET /r/ID: the human-readable report.
Errors
400the address is not allowed (not http or https, or a private network).429daily limit reached.503the queue is full; retry in a few minutes.
Use it in CI
The docs-health GitHub Action wraps these calls and fails a workflow when the grade drops below the one you set.