Markdown Tidy API

Programmatic access to the same clean / repair / convert pipeline that powers the web app. One endpoint, one auth header, returns the converted document directly. Available to all Premium customers.

Quickstart

Generate an API key from your account, then make a single request:

curl https://mdtidy.com/api/v1/convert \
  -H "X-API-KEY: mt_live_abc123…" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# Q2 results\n\nWe shipped …",
    "actions": ["clean","repair"],
    "design_system": "minimal-clean",
    "format": "pdf"
  }'

Authentication

Send your API key in the X-API-KEY request header. Keys are issued from Account → API keys inside Markdown Tidy. Live keys are prefixed mt_live_; test keys are prefixed mt_test_. Never commit keys to source control — use environment variables and rotate keys with the dashboard when needed.

X-API-KEY: mt_live_abc123…

Base URL & versioning

https://mdtidy.com/api/v1

The current API version is v1. We will not make breaking changes to v1. New optional parameters and response fields may be added. Breaking changes ship as v2 with a deprecation window for v1.

POST `/v1/convert`

Clean, repair and convert a Markdown document. Returns the converted output in the requested format.

Request body

Field	Type	Default	Notes
`markdown`	string	—	Required. Markdown source, UTF-8. Max 200 KB per call.
`actions`	array	`["clean","repair"]`	Any subset of `clean` and `repair`. Pass `[]` to skip both (raw render only).
`design_system`	string	`"minimal-clean"`	One of `minimal-clean`, `executive-report`, `developer-docs`, or the ID of a saved custom design system.
`format`	string	`"pdf"`	One of `pdf`, `docx`, `html`, `png`, `text`.

Response — 200 OK

{
  "output": "JVBERi0xLjUKJeLjz9MKMyAwIG9iag…",
  "format": "pdf",
  "content_type": "application/pdf",
  "credits_used": 1,
  "credits_remaining": 1742,
  "warnings": [
    { "rule": "repair.broken-table", "fixes": 3 }
  ]
}

output is the literal text for html and text formats, and base64-encoded bytes for pdf, docx and png. Decode with your language's standard base64 library.

Node example

import { writeFileSync } from "node:fs";

const res = await fetch("https://mdtidy.com/api/v1/convert", {
  method: "POST",
  headers: {
    "X-API-KEY": process.env.MDTIDY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    markdown: "# Report\n\n…",
    format: "pdf",
  }),
});
const data = await res.json();
writeFileSync("report.pdf", Buffer.from(data.output, "base64"));

Python example

import os, base64, requests

r = requests.post(
    "https://mdtidy.com/api/v1/convert",
    headers={"X-API-KEY": os.environ["MDTIDY_API_KEY"]},
    json={"markdown": "# Report\n\n…", "format": "pdf"},
).json()
open("report.pdf", "wb").write(base64.b64decode(r["output"]))

Credits & pricing

Premium ($5 / month) includes 2,000 API credits per month.
1 credit = 1 successful API call, regardless of document size (within the 200 KB limit).
Failed calls (any 4xx or 5xx response) do not consume credits.
Credits reset at the start of each billing month. Unused credits do not roll over.
Need more? Buy credit packs: $5 for 5,000 extra credits, one-time purchase, non-expiring. Stack as many as you need from your account page.

Errors

Errors return as JSON with an appropriate HTTP status. The error.code field is stable and machine-readable.

HTTP	`error.code`	Meaning
400	`invalid_request`	Malformed JSON or missing required parameter.
401	`missing_api_key`	No `X-API-KEY` header on the request.
401	`invalid_api_key`	Unknown, revoked or expired key.
402	`out_of_credits`	Monthly allotment exhausted and no remaining top-up credits.
413	`payload_too_large`	`markdown` exceeds 200 KB.
422	`unsupported_format`	`format` not one of the supported values.
429	`rate_limited`	Too many requests; see `Retry-After` header.
500	`internal_error`	Server-side problem. Safe to retry with backoff.

{
  "error": {
    "code": "out_of_credits",
    "message": "Monthly credits exhausted. Buy a top-up pack to continue.",
    "credits_remaining": 0
  }
}

Rate limits

60 requests per minute per API key, in the default tier. Exceeding the limit returns 429 with a Retry-After header indicating seconds to wait. Higher limits available on request — email support@sudzy.co with your expected volume.

Reliability & quality

The API uses the same conversion pipeline that powers the web app. Output is regression-tested against hundreds of real-world Markdown samples — AI-generated, broken, multilingual, CJK — before every release. Reported failures are added to the regression corpus permanently, so the same bug can't return.

Support

Questions, bug reports, higher-rate-limit requests: email support@sudzy.co. Include your account email, the request ID from the X-Request-ID response header, and a minimal repro.

Try Markdown Tidy free See pricing