---
title: "Clean, repair, and convert markdown"
method: POST
path: "/api/v1/convert"
tags: ["convert"]
---

# Clean, repair, and convert markdown

`POST /api/v1/convert`

## Request

- Base URL: `https://mdtidy.com`
- URL: `https://mdtidy.com/api/v1/convert`
- Auth: API key in header `X-API-KEY`

Runs the markdown through the requested pipeline (clean / repair) and renders to the requested output format. Charges 1 credit per successful render; failures are refunded automatically.

## Request body

- ConvertRequest
  - `markdown` string, required: The markdown source to convert. UTF-8. Hard cap: 1 MB.
  - `format` 'html' | 'text' | 'pdf' | 'docx' | 'png', required: Output format.
  - `designSystem` 'minimal-clean' | 'executive-report' | 'developer-docs': Slug of a built-in design system. Defaults to `minimal-clean`. An unknown slug returns 400 `unknown_design_system`. Available: `minimal-clean` (Minimal Clean), `executive-report` (Executive Report), `developer-docs` (Technical Doc).
  - `settings` ConvertSettings: Per-stage configuration. v1 ships the `tidy` sub-object; future releases extend this surface without flattening the top-level request.
    - `tidy` TidySettings: Configuration for the Tidy stage (cleanup + repair). All fields optional; defaults run the full Tidy pipeline with polish on.
      - `enable` boolean: Run the Tidy pipeline (cleanup + repair) before rendering. Defaults to `true`. Set `false` to render the markdown as-is.
      - `polish` boolean: Apply the opinionated typography polish rules (em-dash → "-", formal phrasings contracted). Defaults to `true`. Only meaningful when `enable` is not `false`.
  - `page` PageSettings: Per-document page geometry + font scale. All fields optional — an omitted field inherits the chosen design system default. Render options only; never affects credits.
    - `paperSize` 'Letter' | 'A4' | 'A3': Paper size. Defaults to the design-system page size.
    - `orientation` 'portrait' | 'landscape': Page orientation. Defaults to the design-system value (portrait).
    - `marginPreset` 'narrow' | 'normal' | 'wide': Margin preset (narrow 12.7mm / normal 25.4mm / wide 38.1mm). Defaults to the design-system preset.
    - `fontScale` 'down' | 'normal' | 'up': Uniform font + typographic-spacing scale (0.75 / 1.0 / 1.25). Defaults to `normal`. Does not change page margins.

## Response `200`

Conversion succeeded.

- ConvertResponse
  - `format` 'html' | 'text' | 'pdf' | 'docx' | 'png', required
  - `contentType` string, required
  - `byteSize` integer, required
  - `designSystem` string, required
  - `output` string: Inline body for text/HTML outputs.
  - `outputBase64` string: Base64-encoded body for binary outputs (PDF/DOCX/PNG).
  - `warnings` object[], required
    - `rule` string, required
    - `fixes` integer, required
  - `creditsCharged` integer, required
  - `creditsRemaining` integer, required
  - `requestId` string, required

## Other responses

- `400`: Schema validation failed.
- `401`: X-API-KEY is malformed, unknown, or revoked.
- `402`: Wallet has insufficient credits to satisfy the request.
- `413`: Request body exceeds the 1 MB cap.
- `422`: Requested format is not one of the supported outputs.
- `429`: Per-key rate limit (60/min) exceeded.
- `500`: Server failed to complete the request.

---

[API](https://skmtc.dev/mdtidy/apis/markdown-tidy-api.md) · [All operations](https://skmtc.dev/mdtidy/apis/markdown-tidy-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mdtidy/apis/markdown-tidy-api/revisions/caeec6fad155?raw)