API Reference — Toolbox Pro

Toolbox Pro API

The Toolbox Pro REST API lets you integrate readability scoring and health literacy compliance checking directly into your EHR, CMS, document management system, or any custom application. Available on Team and Enterprise plans.

⚡ Team plan required. API access is included with Team ($79/mo) and Enterprise plans. Upgrade your plan →

All requests return JSON. All inputs accept plain text. The API processes documents synchronously for single analyses and asynchronously for bulk jobs.

Authentication

All API requests must include your API key in the Authorization header using Bearer token format. Find your API key in the dashboard under Settings → API.

Header

Authorization: Bearer tb_live_your_api_key_here
Content-Type: application/json

⚠️ Never expose your API key in client-side code or public repositories. Rotate keys immediately if compromised.

Base URL

https://api.toolbox.pro/v1

All endpoints below are relative to this base URL. The API is versioned — breaking changes will be introduced under a new version prefix (e.g. /v2) with at least 90 days notice.

Rate Limits

Plan	Single /analyze	Bulk /analyze/bulk	Monthly total
Pro	60 req / min	5 jobs / hour	10,000
Team	200 req / min	20 jobs / hour	Unlimited
Enterprise	Custom	Custom	Custom

Rate limit headers are returned with every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Analyze Text

Score a single document against all readability formulas and healthcare compliance standards.

POST /analyze Single document analysis

curl -X POST https://api.toolbox.pro/v1/analyze \
  -H "Authorization: Bearer tb_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Following your myocardial infarction, it is imperative that you adhere to your prescribed pharmacological regimen...",
    "name": "Discharge Instructions v3",
    "standards": ["ahrq", "ama", "joint_commission"],
    "save": true
  }'

Request Body Parameters

Parameter	Type	Required	Description
text	string	Required	The document text to analyze. Plain text, max 100,000 characters.
name	string	Optional	Human-readable document name for history and exports.
standards	array	Optional	Compliance standards to check: `"ahrq"`, `"ama"`, `"joint_commission"`, `"nih"`. Defaults to all.
save	boolean	Optional	If true, saves result to your analysis history. Default: false.
metadata	object	Optional	Arbitrary key-value pairs attached to the result (e.g. department, author, version).

Response

{ "id": "anlz_01J9K2X...", "name": "Discharge Instructions v3", "created_at": "2026-05-27T14:32:00Z", "scores": { "flesch_reading_ease": 38.2, "flesch_kincaid_grade": 11.4, "gunning_fog": 13.8, "smog_index": 12.9, "coleman_liau": 10.2, "avg_sentence_length": 22.4, "complex_word_pct": 0.31, "syllables_per_word": 2.1 }, "compliance": { "ahrq": { "status": "fail", "target_grade": 6, "actual_grade": 11.4 }, "ama": { "status": "fail", "target_grade": 6, "actual_grade": 11.4 }, "joint_commission": { "status": "fail", "target_grade": 5, "actual_grade": 11.4 } }, "suggestions": [ "Shorten sentences — avg 22.4 words, target under 15", "Replace complex medical terms: 'myocardial infarction' → 'heart attack'", "Use active voice throughout" ], "word_count": 284, "sentence_count": 12 }

Bulk Analysis

Submit up to 100 documents in a single request. The job runs asynchronously — poll the returned job_id to check status.

POST /analyze/bulk Async batch processing

curl -X POST https://api.toolbox.pro/v1/analyze/bulk \
  -H "Authorization: Bearer tb_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      { "name": "Discharge Instructions", "text": "..." },
      { "name": "Consent Form — Hip", "text": "..." },
      { "name": "Diabetes Guide", "text": "..." }
    ],
    "standards": ["ahrq", "ama"],
    "webhook_url": "https://your-system.org/webhooks/readability"
  }'

Poll for results

curl https://api.toolbox.pro/v1/jobs/job_01J9K3X \
  -H "Authorization: Bearer tb_live_your_key"

Analysis History

GET /history Paginated analysis history

curl "https://api.toolbox.pro/v1/history?limit=20&page=1&status=fail" \
  -H "Authorization: Bearer tb_live_your_key"

Query Parameters

Parameter	Type	Description
limit	integer	Results per page. Default: 20, max: 100.
page	integer	Page number. Default: 1.
status	string	Filter by compliance status: `pass`, `warn`, `fail`.
from	string	ISO 8601 date. Return analyses after this date.
to	string	ISO 8601 date. Return analyses before this date.

Export Reports

GET /export Download CSV or PDF report

# CSV export
curl "https://api.toolbox.pro/v1/export?format=csv&from=2026-05-01" \
  -H "Authorization: Bearer tb_live_your_key" \
  -o report.csv

# PDF export (branded with your white-label settings)
curl "https://api.toolbox.pro/v1/export?format=pdf&from=2026-05-01" \
  -H "Authorization: Bearer tb_live_your_key" \
  -o report.pdf

Score Definitions

Field	Range	Description
flesch_reading_ease	0–100	Higher = easier. 70+ recommended for patient materials.
flesch_kincaid_grade	0–18+	U.S. grade level. Target ≤ 6 for patient education.
gunning_fog	0–20+	Grade level. Heavy weight on complex words.
smog_index	0–18+	Preferred formula for health literacy assessment.
coleman_liau	0–18+	Character-based grade level formula.
complex_word_pct	0.0–1.0	Fraction of words with 3+ syllables. Target < 0.10.

Compliance Standards

Standard	Target	Formula Used	Status Logic
ahrq	≤ Grade 6	Avg of FK + SMOG	pass ≤6, warn ≤8, fail >8
ama	≤ Grade 6	FK Grade Level	pass ≤6, warn ≤8, fail >8
joint_commission	≤ Grade 5	FK Grade Level	pass ≤5, warn ≤7, fail >7
nih	≤ Grade 8	FK Grade Level	pass ≤8, warn ≤10, fail >10

Error Codes

200

OK — Analysis successful.

400

Bad Request — Missing or invalid text parameter, or text exceeds 100,000 characters.

401

Unauthorized — Missing or invalid API key.

403

Forbidden — Feature not available on your plan (e.g. bulk upload on Pro).

429

Too Many Requests — Rate limit exceeded. Check X-RateLimit-Reset header.

500

Server Error — Something went wrong on our end. Retry after 30 seconds.

SDKs & Code Examples

Python

import requests

API_KEY = "tb_live_your_key"
BASE_URL = "https://api.toolbox.pro/v1"

def analyze_document(text, name=None):
    response = requests.post(
        f"{BASE_URL}/analyze",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "text": text,
            "name": name,
            "standards": ["ahrq", "ama", "joint_commission"],
            "save": True
        }
    )
    return response.json()

result = analyze_document("Take this pill once a day with water.", "Medication Instructions")
print(f"FK Grade: {result['scores']['flesch_kincaid_grade']}")
print(f"AHRQ Status: {result['compliance']['ahrq']['status']}")

JavaScript / Node

const analyzeDocument = async (text, name) => {
  const response = await fetch('https://api.toolbox.pro/v1/analyze', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.TOOLBOX_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ text, name, standards: ['ahrq', 'ama'], save: true })
  });
  return response.json();
};

// Example: check all docs in a folder
const result = await analyzeDocument(
  "Take your blood pressure pill every morning.",
  "BP Instructions"
);
console.log(result.compliance.ahrq.status); // "pass"