Import Markdown via REST API

Available in Start planBetav2.12.0

The Markdown import API converts .md files into Tiptap JSON format.

Review the postman collection

You can also experiment with the Document Conversion API by heading over to our Postman Collection.

Import Markdown

POST /v2/convert/import/markdown

The /v2/convert/import/markdown endpoint converts Markdown files (.md or .markdown) into Tiptap's JSON format. Upload a file using multipart/form-data.

Example (cURL)

curl -X POST "https://api.tiptap.dev/v2/convert/import/markdown" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-App-Id: YOUR_APP_ID" \
    -F "file=@/path/to/file.md"

Subscription required

This endpoint requires a valid Tiptap subscription. For more details review our pricing page.

Required headers

Name	Description
`Authorization`	The JWT token to authenticate the request. Example: `Bearer your-jwt-token`
`X-App-Id`	The Convert App-ID from the Convert settings page: https://cloud.tiptap.dev/v2/cloud/convert

Body

Name	Type	Required	Description
`file`	`File`	Yes	The Markdown file to convert (`.md` or `.markdown`)
`verbose`	`string`	No	Logging verbosity level (bitmask: 1=log, 2=warn, 4=error)

Response (200 OK)

{
  "data": {
    "content": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "Hello from Markdown!"
            }
          ]
        }
      ]
    }
  },
  "logs": {
    "info": [],
    "warn": [],
    "error": []
  }
}

Error responses

Status	Code	Description
400	`NO_FILE_PROVIDED`	No file was provided
400	`INVALID_FILE_TYPE`	File is not `.md` or `.markdown`
422	`FAILED_TO_GET_FILE_ARRAY_BUFFER`	Failed to read file buffer
500	`FAILED_TO_CONVERT_MARKDOWN_TO_TIPTAP_JSON`	Failed to convert Markdown to JSON

Support & Limitations

Markdown import parses Markdown text into Tiptap JSON via the v2 cloud API. The endpoint supports standard CommonMark and GFM tables. Custom syntaxes used by optional Tiptap extensions (underline, highlight, math) are not parsed by the import service and won't appear in the returned JSON.

Feature	Support
Text content	✓ Paragraphs, headings (1–6), hard breaks
Inline formatting	✓ Bold, italic, strikethrough, inline code
Block elements	✓ Blockquotes, code blocks (fenced with language), horizontal rules
Lists	✓ Bullet lists, ordered lists, task lists, nested lists
Tables	✓ Basic pipe-syntax tables (single header row, no merged cells)
Links	✓ Hyperlinks with text and URL
Images	✓ Image references with alt text
Underline	✗ Custom `++text++` syntax not registered on the server
Highlight	✗ Custom `==text==` syntax not registered on the server
Text color / Font	✗ No Markdown syntax for colors, font family, or font size
Text alignment	✗ No Markdown syntax
Spacing / Indentation	✗ No Markdown syntax
Merged cells	✗ Markdown tables don't support colspan or rowspan
Headers & Footers	✗ No concept in Markdown
Page layout	✗ No page breaks, sections, or page size
Math	✗ $...$ syntax not registered on the server
Footnotes & Endnotes	✗ Not supported in CommonMark

For the full DOCX feature comparison, see the Supported features matrix.

PreviouslyPage breaks

Next upDOCX