Get started in 60 seconds

Convert Markdown to Notion pages (tables, lists, code blocks) with a single API call.

Get API Key View Examples

Pick the fastest path for what you need today.

A

Convert Markdown to Notion blocks

(no Notion auth needed)

  • Call /convert with your API key
  • You get Notion-compatible blocks JSON back
  • Use it anywhere (store, transform, or send to Notion later)
B

Append Markdown into a Notion page

(needs Notion auth)

  • Call /append with your API key, Notion token, and target pageId
  • We convert and write the blocks into your Notion page in one go
Tip: Start with /convert to verify formatting; switch to /append when you're ready to write to Notion.

Setup Guide

For Path A (/convert)

Just need one thing:

  • Get Your Mark2Notion API Key
    Sign up free • 100 requests/month included

That's it! Use the /convert endpoint to get Notion-compatible JSON blocks.

For Working with Notion Pages

Required for /append, /append-blocks, and /notion-to-markdown endpoints. You'll need:

1. Get Your Mark2Notion API Key

Sign up free • 100 requests/month included

2. Create a Notion Integration

  1. Go to notion.so/my-integrations
  2. Click "New integration"
  3. Give it a name and select your workspace
  4. Copy the Internal Integration Token (starts with ntn_)

3. Share Your Notion Page with the Integration

  1. Open your target Notion page
  2. Click the three dots (•••) in the top right corner
  3. Select "Connections" → "Add connection"
  4. Find and select your integration from the list

4. Get Your Page ID

Copy it from your Notion page URL:

https://notion.so/Your-Page-Title-[PAGE_ID_HERE]

The page ID is the 32-character string at the end of the URL (with or without hyphens)

Copy-Paste Examples

Try it instantly — No worries—variables are pre-wired. Paste your API key once, optional Notion token & pageId for /append.

Direct download
A

/convert - Get Notion blocks JSON

curl -X POST "https://api.mark2notion.com/api/convert" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "markdown": "# Task List\n\n- [x] Setup API\n- [ ] Test integration\n\n| Status | Count |\n|--------|-------|\n| Done | 1 |\n| Todo | 1 |"
  }'
B

/append - Write directly to Notion page

curl -X POST "https://api.mark2notion.com/api/append" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "markdown": "# Task List\n\n- [x] Setup API\n- [ ] Test integration\n\n| Status | Count |\n|--------|-------|\n| Done | 1 |\n| Todo | 1 |",
    "pageId": "your-notion-page-id",
    "notionToken": "ntn_your-notion-integration-token"
  }'

Response Examples

A
📊 /convert Response 
{
  "status": "success",
  "data": {
    "blocks": [
      {
        "type": "heading_1",
        "heading_1": {
          "rich_text": [
            {
              "type": "text",
              "text": { "content": "Task List" }
            }
          ]
        }
      },
      {
        "type": "to_do",
        "to_do": {
          "rich_text": [
            { "type": "text", "text": { "content": "Setup API" } }
          ],
          "checked": true
        }
      },
      {
        "type": "to_do",
        "to_do": {
          "rich_text": [
            { "type": "text", "text": { "content": "Test integration" } }
          ],
          "checked": false
        }
      },
      {
        "type": "table",
        "table": {
          "table_width": 2,
          "has_column_header": true,
          "children": [
            { "type": "table_row", "table_row": { "cells": [[{ "type": "text", "text": { "content": "Status" } }],[{ "type": "text", "text": { "content": "Count" } }]] } },
            { "type": "table_row", "table_row": { "cells": [[{ "type": "text", "text": { "content": "Done" } }],[{ "type": "text", "text": { "content": "1" } }]] } },
            { "type": "table_row", "table_row": { "cells": [[{ "type": "text", "text": { "content": "Todo" } }],[{ "type": "text", "text": { "content": "1" } }]] } }
          ]
        }
      }
    ],
    "blockCount": 4
  }
}
B
✅ /append Response 
{
  "status": "success",
  "data": {
    "totalBlocks": 4,
    "requestCount": 1,
    "retryCount": 0,
    "lastBlockId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

✨ Content is now live in your Notion page!

Built for Notion’s limits

We handle the complex stuff

Everything you’d expect to be hard—chunking, retries, formatting edge cases—is handled automatically.

100‑block limit & chunking
Notion caps requests at 100 blocks. The /append endpoint automatically chunks large documents and preserves order.
Rate limits & retries
Automatic exponential backoff and retry logic make sure your content gets through during busy periods.
Raw vs smart processing
/convert returns raw Notion blocks. /append adds smart splitting, list flattening, and validation.
Idempotency
Prevent duplicate content with built‑in idempotency keys.

Frequently asked questions

Does Notion API accept raw Markdown?

No, Notion requires content to be formatted as specific block objects. That's exactly what Mark2Notion does — we convert your Markdown into properly structured Notion blocks that preserve formatting, tables, and complex content.

How do I authenticate with Notion?

You'll need a Notion integration token. Create one at notion.so/my-integrations, add the integration to your page, then pass your pageId and token to the API.

What about tables and code blocks?

Mark2Notion handles complex content perfectly. Tables, code blocks, and nested lists are converted to valid Notion blocks with the right structure and formatting.

What are the limits and pricing?

Free tier includes 100 requests/month. Pro tier is $19/month for 2,000 requests. No limits on content size — the /append endpoint handles chunking automatically. See our pricing page for details.

Build your first Notion page in under a minute

Get API Key Read docs

Guides

Learn how to integrate Mark2Notion into your automation workflows, handle complex scenarios, and get the most out of our API.