API

Send text, a web address or a PDF and get back a version your reader understands, with the same checks as the app: only hard passages are rewritten, and every rewrite must keep the meaning.

The API is part of the Pro and Business plans. Create a key on your account page. Each call counts as one document against your monthly plan.

Authentication

Send your key as a bearer token.

Authorization: Bearer rdbl_…

POST /transform

curl https://readable.md/api/v1/transform \
  -H "Authorization: Bearer $READABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The lessee shall indemnify the lessor against all claims…",
    "audience": "general",
    "output_language": "source"
  }'

For a PDF, send multipart/form-data with a file field (up to 15 MB) and the other fields as form fields.

curl https://readable.md/api/v1/transform \
  -H "Authorization: Bearer $READABLE_API_KEY" \
  -F file=@contract.pdf -F audience=customers

Body

text	string	The text to make readable.
url	string	A public web page to read instead.
audience	string	Who should understand it. Sets the reader and a starting level.
reader	string	Your own description of the reader, up to 400 characters. Overrides the audience's description.
level	0–5	Target difficulty. Overrides the audience's level. Default 2 (Plain).
output_language	string	"source" keeps the original language; any language name translates while adapting.
stream	boolean	Stream NDJSON events as passages finish instead of one JSON response.

Send exactly one of text, url or a file.

Audiences

general General audience
customers Customers
patients Patients
second-language Second-language reader
young Young reader
newcomer New to the field
decision-maker Decision-maker
specialist Specialist

Levels

0 Very simple (A1–A2)
1 Simple (A2–B1)
2 Plain (B1–B2)
3 Standard (B2–C1)
4 Advanced (C1)
5 Expert (C2)

Response

{
  "id": "5f0c…",
  "share_url": "https://readable.md/r/5f0c…",
  "title": "…",
  "language": "en",
  "settings": { "level": 2, "outputLanguage": "source" },
  "stats": { … reading level before and after, passages checked … },
  "blocks": [ { "id": "b1", "original": "…", "output": "…", "status": "…", "terms": [], … } ],
  "markdown": "# …"
}

markdown is the readable version as one document. blocks holds each passage with its original, the decision made and the checks it passed. A passage whose rewrite could not pass the meaning check keeps its original text.

GET /usage

curl https://readable.md/api/v1/usage -H "Authorization: Bearer $READABLE_API_KEY"

{ "plan": "pro", "documents_used": 42, "documents_limit": 1000,
  "characters_per_document": 200000 }

Errors

Errors return { "error": { "code": "…", "message": "…" } }.

400	invalid_request, invalid_source	The body or the source could not be used.
401	unauthorized	Missing, unknown or revoked key.
403	plan, banned	The plan has no API access, or the account is suspended.
429	quota	This month's documents are used up.
429	rate	Too many documents in the last minute.
500	internal	The run failed on our side. It is not counted.