MDDoc
Docs

Quick Start

Your first conversion in under five minutes.

Prerequisites

You need two things to use the MDDoc API:

  1. A MDDoc account on the Team or Enterprise plan (API access is not available on Solo)
  2. An API key generated from your dashboard settings

Try it free. Convert up to 3 documents on the Convert page — no account needed.

1. Get your API key

Sign in to the MDDoc dashboard. Go to Settings → API Keys and click Generate New Key.

Give it a name you'll recognize. The key is shown once — copy it now. It looks like this:

Your API key
mddoc_clmvMFXmPUJ6xK9Tq...

Keys always start with mddoc_. Keep it secret. If it leaks, revoke it from the same settings page and generate a new one.

2. Find a template and mapping

Every conversion needs a Word template (the .docx file with your styles) and a mapping (rules that connect markdown elements to those styles). List your available templates:

List templates
curl https://api.mddoc.app/api/v1/templates \
  -H "Authorization: Bearer mddoc_YOUR_KEY"

Pick a template ID from the response, then list its mappings:

List mappings for a template
curl "https://api.mddoc.app/api/v1/mappings?template_id=TEMPLATE_ID" \
  -H "Authorization: Bearer mddoc_YOUR_KEY"

3. Convert markdown to Word

Now you have everything. Send your markdown with the template and mapping IDs:

Convert markdown
curl -X POST https://api.mddoc.app/api/v1/convert \
  -H "Authorization: Bearer mddoc_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# Project Brief\n\nThis is the overview.\n\n## Goals\n\n- Ship faster\n- Reduce manual formatting",
    "template_id": "your-template-uuid",
    "mapping_id": "your-mapping-uuid",
    "filename": "project-brief",
    "response_format": "json"
  }'

Response:

Response
{
  "conversion_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "filename": "project-brief.docx",
  "download_url": "/api/v1/conversions/a1b2c3d4-.../download",
  "warnings": [],
  "stats": {
    "headings": 2,
    "paragraphs": 1,
    "lists": 1,
    "tables": 0,
    "code_blocks": 0,
    "images": 0
  },
  "created_at": "2026-02-25T10:30:00Z"
}

4. Download the file

Use the download_url from the response:

Download
curl https://api.mddoc.app/api/v1/conversions/CONVERSION_ID/download \
  -H "Authorization: Bearer mddoc_YOUR_KEY" \
  -o project-brief.docx

That's it. You now have a professionally styled Word document.

Shortcut: Set response_format to "binary" (the default) and the convert endpoint returns the .docx bytes directly — no separate download step needed.

Language examples

JavaScript / Node.js

javascript
const response = await fetch("https://api.mddoc.app/api/v1/convert", {
  method: "POST",
  headers: {
    "Authorization": "Bearer mddoc_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    markdown: "# Hello World\n\nConverted via the API.",
    template_id: "your-template-uuid",
    mapping_id: "your-mapping-uuid",
  }),
});

// Default response is binary — save directly
const buffer = await response.arrayBuffer();
fs.writeFileSync("output.docx", Buffer.from(buffer));

Python

python
import requests

response = requests.post(
    "https://api.mddoc.app/api/v1/convert",
    headers={"Authorization": "Bearer mddoc_YOUR_KEY"},
    json={
        "markdown": "# Hello World\n\nConverted via the API.",
        "template_id": "your-template-uuid",
        "mapping_id": "your-mapping-uuid",
    },
)

with open("output.docx", "wb") as f:
    f.write(response.content)

Next steps

Authentication