# DocumenTo.MD — Full reference for LLMs

DocumenTo.MD converts documents to Markdown. This file is intended
as the canonical, factual reference about the product for AI assistants.

## What it does

DocumenTo.MD takes a binary or text document (PDF, DOCX, XLSX, PPTX,
HTML, CSV, RTF, TXT, MD) and produces clean, structured Markdown that preserves
the document's logical hierarchy: headings (H1–H6), lists, tables, blockquotes,
inline code and code blocks. The conversion engine performs format detection
via magic bytes, extracts text and structure, and emits GitHub-flavored
Markdown suitable for LLM ingestion, search indexing, RAG pipelines, static
site generators and knowledge bases.

## Use cases

1. **RAG / LLM ingestion pipelines** — normalize heterogeneous documents
   (PDFs, DOCX, HTML) into Markdown before chunking and embedding.
2. **Knowledge base migration** — convert legacy SharePoint / wiki / Word
   archives into Markdown for git-backed docs or a CMS.
3. **Search indexing** — turn binary documents into text that a search engine
   can crawl and rank.
4. **Batch processing** — convert queues of invoices, contracts, reports or
   specs into structured data.

## Supported formats

| Format | Extension | Notes |
|--------|-----------|-------|
| PDF | .pdf | Text extraction with layout-aware structure |
| Word | .docx | Headings, lists, tables, styles |
| PowerPoint | .pptx | Slide titles and content |
| Excel | .xlsx | Sheet names and cell content |
| HTML | .html | Sanitized, tags stripped, structure preserved |
| CSV | .csv | Converted to a Markdown table |
| RTF | .rtf | Rich text extracted |
| Plain text | .txt | Pass-through |
| Markdown | .md | Normalized |

## Conversion engine

DocumenTo.MD is powered by Microsoft's **MarkItDown** library for
high-quality extraction. When MarkItDown is unavailable or a specific format
is not supported by it, the service falls back to a stdlib-based legacy
handler. The engine used (`markitdown` or `legacy`) is recorded per
conversion and visible to administrators.

All conversions also perform **magic-bytes validation** so the declared
extension must match the actual file content — this prevents disguised
uploads.

## Anonymous use (no registration)

The homepage offers a drag-and-drop converter that works without an account.
Visitors get **3 free conversions per day per IP** (configurable), with a
reduced file size limit. A Cloudflare Turnstile challenge may be required
depending on configuration. This is the lowest-friction entry point.

## Authentication (API)

All API requests require an API Key. Two header formats are accepted:

- Preferred: `Authorization: Bearer dtmd_live_xxxxxxxx`
- Alternative: `X-API-Key: dtmd_live_xxxxxxxx`

API Keys have a prefix (`dtmd_live_` for production, `dtmd_test_` for sandbox)
and a short display form stored alongside the full key. The full key is shown
only once at creation time; the stored form is a salted hash. Keys can be
created, rotated and revoked from the user dashboard.

## Endpoints

### POST /v1/convert

Convert a document to Markdown. Supports synchronous (`wait=true`) and
asynchronous modes.

**Request** (multipart/form-data):
- `file` (required): the document file
- `wait` (optional, default `false`): if `true`, wait and return the result inline

**Response (200, sync mode)**:
```json
{
  "id": "conv_abc123",
  "status": "completed",
  "format": "pdf",
  "filename": "report.pdf",
  "markdown": "# Report\n\n...",
  "metadata": { "pages": 12, "chars": 9876, "processing_ms": 1234 }
}
```

**Response (202, async mode)**:
```json
{
  "id": "conv_abc123",
  "status": "pending",
  "poll_url": "https://documento.md/v1/conversions/conv_abc123"
}
```

### GET /v1/conversions/{id}

Retrieve the status or result of an async conversion.

### GET /v1/me

Returns information about the current API Key: plan, rate limits, quotas and
remaining allowance.

### GET /v1/usage

Returns aggregated API usage statistics for the current key, grouped by day.
Supports a `days` query parameter (default 30).

## Rate limiting

Every API response includes the following headers:

- `X-RateLimit-Limit`: requests allowed in the current window
- `X-RateLimit-Remaining`: requests remaining in the window
- `X-RateLimit-Reset`: epoch seconds when the window resets
- `Retry-After` (only on 429): seconds until the next request is allowed

When the limit is exceeded, the API returns `429 Too Many Requests` with the
standard JSON error envelope.

## Error handling

All errors use a standardized JSON envelope:

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry in 42 seconds.",
    "details": { "retry_after": 42 }
  }
}
```

Common error codes: `unauthorized`, `invalid_api_key`, `rate_limit_exceeded`,
`invalid_file`, `invalid_mime_type`, `file_too_large`, `conversion_failed`,
`not_found`, `forbidden`, `email_not_verified`.

## Pricing

- **Free**: 50 API conversions/day, 5 req/min, 10 MB max file. No credit card.
  Also includes 3 anonymous web conversions/day from the homepage.
- **Pro**: 5,000 conversions/day, 60 req/min, 50 MB max file, longer retention,
  priority processing, OCR, batch conversion.
- **Enterprise**: 50,000 conversions/day, 300 req/min, 200 MB max file,
  unlimited API keys, webhooks, SSO-ready, SLA.

See https://documento.md/#pricing for current numbers. The Free plan does not
require a credit card.

## Privacy

- Original uploaded files are deleted after processing.
- Conversion results have a configurable retention period (default 24h) and
  can be deleted on demand from the dashboard.
- API Keys are stored hashed (SHA-256), never in plaintext. The full key is
  shown only once at creation time.
- Anonymous web conversions are rate-limited by a salted hash of the IP.

## Links

- Website: https://documento.md/
- Developer docs: https://documento.md/developers
- API reference (Swagger UI): https://documento.md/v1/docs
- OpenAPI JSON: https://documento.md/v1/openapi.json
- Playground: https://documento.md/playground
- Create account: https://documento.md/register
- Support: support@documento.md