# mdworker

> mdworker is an HTTP API from TLE Labs that converts HTML, DOCX, PDF, PPTX and XLSX files to clean Markdown, with OCR for scans and pictures, billed in credits per page.

- Base URL: `https://api.md.tlelabs.com`. Every endpoint except `GET /v1/health` needs `Authorization: Bearer <api_key>`.
- `POST /v1/convert` takes one file as multipart/form-data (`file`, optional `ocr`, `ocr_model`, `preserve_images`) and returns JSON or, with `Accept: text/markdown`, the Markdown itself.
- Credits: 1 per page read from the file, 3 per OCR page with `ocr_model=auto`; nothing is charged for a failed request. Credits are added by the operator (md@tlelabs.com).
- Each page below is plain Markdown. Treat these docs as the current contract; do not infer unlisted fields, headers or endpoints.

## Docs

- [Docs](https://md.tlelabs.com/docs.md): mdworker converts HTML, DOCX, PDF, PPTX and XLSX files to clean Markdown over one HTTP request, with OCR for scans and pictures, billed in credits per page.

## Start here

- [Quickstart](https://md.tlelabs.com/docs/quickstart.md): Create an API key in the dashboard and convert your first document with curl, JavaScript or Python.
- [Authentication](https://md.tlelabs.com/docs/authentication.md): Every request except GET /v1/health sends an API key as a Bearer token; keys belong to an account and share its wallet.

## API reference

- [Convert a file](https://md.tlelabs.com/docs/convert.md): POST /v1/convert takes one document as multipart/form-data and returns its Markdown as JSON or as plain text/markdown.
- [Quote before converting](https://md.tlelabs.com/docs/quote.md): POST /v1/quote prices several files at once without converting them, calling OCR, reserving credits or charging anything.
- [Wallet](https://md.tlelabs.com/docs/wallet.md): GET /v1/wallet returns the account's balance, reserved and available credits; GET /v1/wallet/transactions lists charges and top-ups.
- [Health and status](https://md.tlelabs.com/docs/health-and-status.md): GET /v1/health reports the API and OCR provider status without authentication; status.md.tlelabs.com shows the last hour, day and month.

## Concepts

- [OCR models](https://md.tlelabs.com/docs/ocr-models.md): Choose the OCR model per request with ocr_model; auto tries a chain of models and falls back on failure.
- [Formats, pages and pricing](https://md.tlelabs.com/docs/formats-and-pricing.md): What mdworker extracts from each format, how billed pages are counted, what a conversion costs and the limits per request.
- [Errors](https://md.tlelabs.com/docs/errors.md): Every error is JSON with a code and a message; no credits are charged for a failed request, with one documented 503 exception.
- [Rate limits](https://md.tlelabs.com/docs/rate-limits.md): Each API key may run a few conversions at the same time; extra requests get 429 too_many_concurrent with Retry-After.

## Optional

- [Complete documentation](https://md.tlelabs.com/llms-full.txt): Every docs page in one Markdown file
- [Status](https://status.md.tlelabs.com): Service and OCR provider health (JSON at /api/status)