Conversion API

Every endpoint, every parameter, every error code.

Base URL

text

https://api.mddoc.app

All endpoints are prefixed with /api/v1. Every request requires a Bearer token in the Authorization header. See Authentication.

Request & response format

Request bodies are JSON with Content-Type: application/json
Successful responses return JSON or binary data depending on the endpoint
Errors always return a JSON envelope with an error object

Error envelope

{
  "error": {
    "code": "validation_error",
    "message": "Field 'markdown' is required."
  }
}

POST

/api/v1/convert

Convert markdown to a Word document. This is the core endpoint — it takes your markdown, applies a template and style mapping, and returns a .docx file.

Request body

Field	Type	Required	Description
markdown	string	Yes	Raw markdown content. Minimum 1 character.
template_id	string (UUID)	Yes	ID of the Word template to use.
mapping_id	string (UUID)	Yes	ID of the style mapping to apply.
filename	string	No	Output filename without extension. Default: "document"
response_format	string	No	"binary" (default) returns raw .docx bytes. "json" returns metadata with a download URL.

Binary response (default)

Returns the .docx file directly. Check these response headers:

Header	Description
Content-Type	application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition	Filename for the download
X-Conversion-Id	UUID of the conversion record
X-Warnings	JSON array of warning strings (if any)

JSON response

When response_format: "json", returns metadata and a download URL:

JSON response

{
  "conversion_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "filename": "document.docx",
  "download_url": "/api/v1/conversions/a1b2c3d4-.../download",
  "warnings": ["missing_style: Code Block"],
  "stats": {
    "headings": 8,
    "paragraphs": 23,
    "lists": 6,
    "tables": 2,
    "code_blocks": 5,
    "images": 0
  },
  "created_at": "2026-02-25T10:30:00Z"
}

Warnings tell you when a markdown element had no matching style in the template, or when a mapping rule references a style that doesn't exist. The conversion still completes — it falls back to the default style.

Example

Convert with binary response

curl -X POST https://api.mddoc.app/api/v1/convert \
  -H "Authorization: Bearer mddoc_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# Quarterly Report\n\n## Summary\n\nRevenue grew 15%.",
    "template_id": "550e8400-e29b-41d4-a716-446655440000",
    "mapping_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  }' \
  -o report.docx

GET

/api/v1/conversions/:id

Check the status of a conversion. Useful when you need to poll for completion or retrieve metadata after a binary conversion.

Response

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

Possible status values: pending, processing, completed, failed.

GET

/api/v1/conversions/:id/download

Download the converted .docx file. Returns the raw binary with appropriate content headers. The conversion must have status completed.

Download a conversion

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

GET

/api/v1/templates

List all Word templates available to your account. Templates are managed via the dashboard — this endpoint is read-only.

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Corporate Report",
    "description": "Standard quarterly report template with cover page",
    "version": 3,
    "created_at": "2026-01-15T09:00:00Z",
    "updated_at": "2026-02-20T14:30:00Z"
  },
  {
    "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "name": "Technical Spec",
    "description": "Engineering specification with appendix sections",
    "version": 1,
    "created_at": "2026-02-01T11:00:00Z",
    "updated_at": "2026-02-01T11:00:00Z"
  }
]

To learn how templates work and how to create them, see Templates & Mappings.

GET

/api/v1/mappings

List style mappings. Optionally filter by template.

Query parameters

Parameter	Type	Description
template_id	string (UUID)	Optional. Only return mappings for this template.

Response

[
  {
    "id": "mapping-uuid-here",
    "name": "Default Corporate Mapping",
    "template_id": "550e8400-e29b-41d4-a716-446655440000",
    "version": 2,
    "rules": {
      "heading": { "1": "Heading 1", "2": "Heading 2", "3": "Heading 3" },
      "paragraph": "Normal",
      "list_bullet": "List Bullet",
      "list_ordered": "List Number",
      "code_block": "Code",
      "blockquote": "Quote",
      "table": { "style": "Grid Table 1 Light", "header_row": true }
    },
    "created_at": "2026-01-15T09:30:00Z",
    "updated_at": "2026-02-18T16:00:00Z"
  }
]

Error codes

All errors follow the same envelope format. Here's the complete list:

HTTP	Code	When
401	missing_api_key	No Authorization header provided
401	invalid_api_key	Key is invalid, revoked, or wrong format
403	api_access_denied	Plan doesn't include API access
404	not_found	Template, mapping, or conversion not found
422	validation_error	Request body failed validation
429	rate_limit_exceeded	Monthly conversion quota exhausted
500	internal_error	Server error — retry or contact support

Conversion quotas

Solo plans get 20 conversions per month. Team and Enterprise plans are unlimited. When your quota is exhausted, the convert endpoint returns 429 rate_limit_exceeded.

Check your current usage via the dashboard billing page. Quotas reset on your billing anniversary date each month.

Supported markdown

The conversion engine parses standard markdown plus these extensions:

Element	Support
Headings (h1–h6)	Full
Paragraphs	Full
Bold, italic, strikethrough	Full
Ordered & unordered lists	Up to 3 nesting levels
Code blocks	Full (Courier New, 9pt)
Inline code	Full
Blockquotes	Full
Tables	Full (with header rows)
Links	Converted to hyperlinks
Images	Placeholder text inserted
Horizontal rules	Converted to page breaks
Task lists	Parsed (rendered as lists)

Authentication Templates & Mappings