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 or our append endpoint. 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~~
  • 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 ___

​
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 which includes smart processing for large content, text splitting, and validation.