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 ($149/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 & Versioning

Every request to the Toolbox Pro API is made to a single base URL. All endpoints documented here are relative paths appended to this base — you never call an endpoint on its own.

Production Base URL

https://api.cleartext.health/v1

How to Read the URL

https://api.cleartext.health/v1/analyze

Protocol — https://All API traffic is encrypted over TLS. HTTP requests are not accepted.

Domain — api.cleartext.healthThe dedicated API subdomain. Separate from the web app at cleartext.health.

Version — /v1The API version. Pinned so changes to future versions never break your integration.

Endpoint — /analyzeThe specific operation you're calling. Changes with each request.

Constructing a Full Request URL

Always combine the base URL with the endpoint path. Never call an endpoint path on its own.

# Base URL
https://api.cleartext.health/v1

# Endpoint path (as shown in these docs)
/analyze

# Full URL you actually call
https://api.cleartext.health/v1/analyze

# Another example — history endpoint
https://api.cleartext.health/v1/history?limit=20&page=1

In Code

We recommend storing the base URL as a constant in your code so you only ever need to update it in one place.

# Python
BASE_URL = "https://api.cleartext.health/v1"
response = requests.post(f"{BASE_URL}/analyze", headers=..., json=...)

// JavaScript
const BASE_URL = 'https://api.cleartext.health/v1';
const response = await fetch(`${BASE_URL}/analyze`, { method: 'POST', ... });

API Versioning

The API version is part of the URL path (/v1). This means your integration is pinned to a specific version — we can release new versions without breaking your existing code.

Version	Status	Base URL	Notes
v1	Active	`api.cleartext.health/v1`	Current stable version. All new integrations should use v1.
v2	Planned	`api.cleartext.health/v2`	In development. Will be announced with a 90-day migration window before v1 deprecation.

📌 Version stability guarantee. We will never introduce breaking changes to /v1. When a new version ships, you'll receive at least 90 days notice before v1 is deprecated, giving you time to migrate on your own schedule.

Environments

The API currently operates in a single production environment. A sandbox environment for testing without affecting your usage quota is on the roadmap.

Environment	Base URL	Status	Notes
Production	`api.cleartext.health/v1`	Live	Real data. Counts against your rate limits and monthly quota.
Sandbox	`sandbox.cleartext.health/v1`	Coming Soon	Test your integration freely. No quota usage, no real data stored.

⚠️ Always use HTTPS. The API does not accept plain HTTP connections. Requests over HTTP will be rejected with a connection error before reaching our servers.

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.cleartext.health/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 10 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.cleartext.health/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"
  }'

⚠️ Bulk limit is 10 documents per job. Break larger batches into multiple requests. Each job counts as one bulk slot against your hourly limit.

Poll for results

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

Analysis History

GET /history Paginated analysis history

curl "https://api.cleartext.health/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.cleartext.health/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.cleartext.health/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.cleartext.health/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 BASE_URL = 'https://api.cleartext.health/v1';

const analyzeDocument = async (text, name) => {
  const response = await fetch(`${BASE_URL}/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();
};

const result = await analyzeDocument(
  "Take your blood pressure pill every morning.",
  "BP Instructions"
);
console.log(result.compliance.ahrq.status); // "pass"