Skip to main content
POST
/
api
/
convert
Convert Markdown
curl --request POST \
  --url https://api.mark2notion.com/api/convert \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{
  "markdown": "<string>"
}'
{
  "status": "success",
  "data": {
    "blocks": [
      {
        "type": "heading_1",
        "heading_1": {
          "rich_text": [
            {
              "type": "text",
              "text": {
                "content": "My Heading"
              }
            }
          ]
        }
      },
      {
        "type": "paragraph",
        "paragraph": {
          "rich_text": [
            {
              "type": "text",
              "text": {
                "content": "This is a "
              }
            },
            {
              "type": "text",
              "text": {
                "content": "bold"
              },
              "annotations": {
                "bold": true
              }
            },
            {
              "type": "text",
              "text": {
                "content": " paragraph with a "
              }
            },
            {
              "type": "text",
              "text": {
                "content": "link",
                "link": {
                  "url": "https://example.com"
                }
              }
            },
            {
              "type": "text",
              "text": {
                "content": "."
              }
            }
          ]
        }
      },
      {
        "type": "bulleted_list_item",
        "bulleted_list_item": {
          "rich_text": [
            {
              "type": "text",
              "text": {
                "content": "List item 1"
              }
            }
          ]
        }
      },
      {
        "type": "bulleted_list_item",
        "bulleted_list_item": {
          "rich_text": [
            {
              "type": "text",
              "text": {
                "content": "List item 2"
              }
            }
          ]
        }
      }
    ],
    "blockCount": 4
  }
}

​
Overview

The convert endpoint transforms Markdown text into Notion block objects that can be used with the Notion API, our append endpoint, or the append-blocks endpoint when you need to append prebuilt blocks. Our converter supports a comprehensive set of Markdown features including GitHub Flavored Markdown (GFM) alerts, advanced formatting, and intelligent text splitting.

​
Supported Markdown Features

​
Basic Elements

  • Headings: #, ##, ###, ####, #####, ###### (H4-H6 map to heading_3)
  • Paragraphs: Regular text and line breaks
  • Text Formatting: **bold**, *italic*, `code`, ~~strikethrough~~
  • Colors: <span style="color: red">colored text</span> (supports 9 Notion colors)
  • Links: [text](url) and <https://example.com> autolinks
  • Images: ![alt text](image-url)

​
Lists

  • Bulleted Lists: - item or * item
  • Numbered Lists: 1. item
  • Nested Lists: Unlimited nesting depth supported
  • Mixed Lists: Combine bulleted and numbered at different levels

​
Code

  • Inline Code: `code`
  • Code Blocks: ```language with syntax highlighting
  • Indented Code: 4+ space indentation

​
Advanced Features

  • Tables: Full Markdown table support with headers
  • Blockquotes: > quoted text
  • GFM Alerts: > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], > [!CAUTION]
  • Horizontal Rules: ---, ***, or ___

​
HTML Color Support

Add colors to your text using standard HTML syntax: 
This is <span style="color: red">red text</span> and <span style="color: blue">blue text</span>.
Supported Colors:
  • red, blue, green, yellow, orange, purple, pink, gray (or grey), brown
Features:
  • Works with all block types (headings, lists, quotes, etc.)
  • Can be combined with other formatting (bold, italic, etc.)
  • Unsupported colors are silently ignored
Examples: 
# Heading with <span style="color: purple">purple text</span>

Paragraph with **bold <span style="color: red">red</span>** text.

- List item with <span style="color: green">green text</span>

​
Generated Notion Block Types

Markdown ElementNotion Block TypeNotes
# Headingheading_1, heading_2, heading_3H4-H6 map to heading_3
TextparagraphWith rich text formatting
- Itembulleted_list_itemUnlimited nesting
1. Itemnumbered_list_itemUnlimited nesting
```code```codeWith language support
> QuotequoteStandard blockquotes
> [!NOTE]calloutWith icons and colors
![alt](url)imageExternal images
| Table |tableWith headers
---dividerHorizontal rules

​
Text Length Handling

​
Automatic Text Splitting

Content longer than 2000 characters is automatically split across multiple rich_text objects within the same block:
  • ✅ No content loss: All text is preserved
  • ✅ Smart splitting: Breaks at safe boundaries when possible
  • ✅ Maintains formatting: Bold, italic, and other formatting preserved across splits
  • ✅ Transparent: The splitting is handled automatically

​
Example: Long Content

{
  "type": "paragraph",
  "paragraph": {
    "rich_text": [
      {
        "type": "text",
        "text": { "content": "First 2000 characters of content..." }
      },
      {
        "type": "text", 
        "text": { "content": "...remaining characters continue here" }
      }
    ]
  }
}

​
Request

​
x-api-key
string
required
Your Mark2Notion API key
​
markdown
string
required
The Markdown content to convert to Notion blocks

​
Response

​
status
string
Will be “success” for successful requests
​
data
object

​
Examples

curl -X POST "https://api.mark2notion.com/api/convert" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "markdown": "# My Heading\n\nThis is a **bold** paragraph with a [link](https://example.com).\n\n> [!NOTE]\n> This is a GitHub-flavored alert that becomes a callout!\n\n- List item 1\n- List item 2\n\n---\n\n## Code Example\n\n```javascript\nconsole.log(\"Hello World!\");\n```"
  }'

{
  "status": "success",
  "data": {
    "blocks": [
      {
        "type": "heading_1",
        "heading_1": {
          "rich_text": [
            {
              "type": "text",
              "text": {
                "content": "My Heading"
              }
            }
          ]
        }
      },
      {
        "type": "paragraph",
        "paragraph": {
          "rich_text": [
            {
              "type": "text",
              "text": {
                "content": "This is a "
              }
            },
            {
              "type": "text",
              "text": {
                "content": "bold"
              },
              "annotations": {
                "bold": true
              }
            },
            {
              "type": "text",
              "text": {
                "content": " paragraph with a "
              }
            },
            {
              "type": "text",
              "text": {
                "content": "link",
                "link": {
                  "url": "https://example.com"
                }
              }
            },
            {
              "type": "text",
              "text": {
                "content": "."
              }
            }
          ]
        }
      },
      {
        "type": "bulleted_list_item",
        "bulleted_list_item": {
          "rich_text": [
            {
              "type": "text",
              "text": {
                "content": "List item 1"
              }
            }
          ]
        }
      },
      {
        "type": "bulleted_list_item",
        "bulleted_list_item": {
          "rich_text": [
            {
              "type": "text",
              "text": {
                "content": "List item 2"
              }
            }
          ]
        }
      }
    ],
    "blockCount": 4
  }
}

​
Error Responses

Handle Errors

Understand error responses and how to handle them.

​
Usage Notes

Each convert request counts as 1 API call against your quota, regardless of the markdown size.
The returned blocks are standard Notion API block objects and can be used directly with the Notion API.
The convert endpoint returns raw Notion blocks without additional processing. For content that will be sent to Notion, consider using the /append endpoint for Markdown sources or /append-blocks when you already have block JSON. Both include smart processing for large payloads, text splitting, and validation.