Skip to main content
POST
/
api
/
notion-to-markdown
Notion to Markdown
curl --request POST \
  --url https://api.mark2notion.com/api/notion-to-markdown \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{
  "notionToken": "<string>",
  "pageId": "<string>"
}'
{
  "status": "success",
  "data": {
    "markdown": {
      "parent": "# My Page Title\n\nThis is a paragraph with **bold** text and *italic* text.\n\n## Subheading\n\n- List item 1\n- List item 2\n  - Nested item\n\n---\n\n```javascript\nconsole.log('Code block');\n```\n\n> This is a quote block\n\n| Column 1 | Column 2 |\n|----------|----------|\n| Cell 1   | Cell 2   |"
    },
    "pageId": "abc123def456"
  }
}

​
Overview

The notion-to-markdown endpoint retrieves content from a Notion page and converts it to Markdown format. This is useful for exporting Notion content, creating backups, or integrating Notion content with other Markdown-based systems.

​
Supported Block Types

The converter supports a comprehensive set of Notion block types:

​
Text Blocks

  • Paragraphs: Standard text blocks
  • Headings: H1, H2, H3 (converted to #, ##, ###)
  • Quotes: Blockquote blocks
  • Callouts: Notion callouts (converted to GFM-style alerts when possible)
  • Code Blocks: With language syntax support

​
Lists

  • Bulleted Lists: Converted to - items
  • Numbered Lists: Converted to 1. items
  • To-do Lists: Converted to - [ ] or - [x] checkboxes
  • Nested Lists: Full nesting support

​
Media & Embeds

  • Images: Converted to ![alt](url) format
  • External Images: Both uploaded and external images supported

​
Advanced Blocks

  • Tables: Full table support with headers
  • Dividers: Converted to ---
  • Child Pages: Referenced in the output
  • Child Databases: Referenced in the output

​
Request

​
x-api-key
string
required
Your Mark2Notion API key
​
notionToken
string
required
Your Notion integration token (starts with secret_)
​
pageId
string
required
The ID of the Notion page to convert. Can be a 32-character ID or UUID format

​
Response

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

​
Examples

curl -X POST "https://api.mark2notion.com/api/notion-to-markdown" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "notionToken": "secret_your_notion_token",
    "pageId": "abc123def456"
  }'

{
  "status": "success",
  "data": {
    "markdown": {
      "parent": "# My Page Title\n\nThis is a paragraph with **bold** text and *italic* text.\n\n## Subheading\n\n- List item 1\n- List item 2\n  - Nested item\n\n---\n\n```javascript\nconsole.log('Code block');\n```\n\n> This is a quote block\n\n| Column 1 | Column 2 |\n|----------|----------|\n| Cell 1   | Cell 2   |"
    },
    "pageId": "abc123def456"
  }
}

​
Error Responses

Handle Errors

Understand error responses and how to handle them.

​
Common Errors

Status Code: 401 UnauthorizedThe Notion token provided is invalid or expired. Make sure you’re using a valid integration token.
Status Code: 404 Not FoundThe page ID doesn’t exist or your integration doesn’t have access to it. Verify the page ID and ensure the page is shared with your integration.
Status Code: 403 ForbiddenYour Notion integration doesn’t have permission to access this page. Share the page with your integration in Notion.

​
Response Structure

The markdown field in the response is an object that separates parent and child page content:
  • parent: Contains the main page’s Markdown content
  • [Child Page Title]: If the page has child pages, each will be a separate property named after the child page title, containing that child’s Markdown content
This structure allows you to:
  • Access the main content via data.markdown.parent
  • Iterate over child pages if they exist
  • Maintain the hierarchy of your Notion page structure

​
Usage Notes

Each notion-to-markdown request counts as 1 API call against your quota, regardless of the page size or number of child pages.
The endpoint returns standard Markdown that’s compatible with GitHub Flavored Markdown (GFM) and most Markdown processors.
Make sure your Notion integration has been granted access to the page you want to convert. Pages must be explicitly shared with your integration.

​
Setup Guide

To use this endpoint, you need a Notion integration token:
  1. Go to https://www.notion.so/my-integrations
  2. Click “New integration”
  3. Give it a name and select the workspace
  4. Copy the “Internal Integration Token” (starts with secret_)
  5. Share the pages you want to convert with this integration

​
Use Cases

  • Content Backup: Export Notion pages to Markdown for backup purposes
  • Static Site Generation: Convert Notion content to Markdown for static site generators
  • Documentation Sync: Keep documentation in Notion and export to Markdown-based systems
  • Content Migration: Move content from Notion to other platforms
  • Version Control: Track Notion content changes in Git using Markdown format
⌘I