infoharness

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": true to 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

  • 400 the address is not allowed (not http or https, or a private network).
  • 429 daily limit reached.
  • 503 the 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.