# Append to Notion Page
Source: https://docs.mark2notion.com/api-reference/append
POST https://api.mark2notion.com/api/append
Convert Markdown and append it directly to a Notion page
## Overview
The append endpoint converts Markdown text to Notion blocks and appends them directly to an existing Notion page. This combines the convert functionality with direct Notion integration.
**Full Markdown Support**: The append endpoint uses the same conversion engine as the `/api/convert` endpoint, which means it supports all markdown features including:
* HTML colors: `colored text`
* Toggle blocks: `Title
Content `
* GFM alerts (callouts): `> [!NOTE]`, `> [!WARNING]`, etc.
* Nested lists with unlimited depth
* Tables with headers
* All standard formatting (bold, italic, code, strikethrough)
If you already have Notion block JSON (for example from a previous `/convert` call or another system), use the [`/append-blocks`](./append-blocks) endpoint to append without reconverting.
## Request
Your Mark2Notion API key
The Markdown content to convert and append. The API accepts both actual newlines and escaped sequences (`\n`, `\r\n`, `\r`), so you can use either format based on your tooling.
Your Notion integration token. Optional when your workspace is connected via OAuth in the dashboard. Pass this if you prefer to authenticate with a manual integration token instead. See [Using a Manual Notion Token](/quickstart#using-a-manual-notion-token-advanced).
The URL or page ID of the Notion page to append content to. Pass the full `notion.so` page URL or just the page ID โ both are accepted.
Optional block ID to append content after. If not provided, content is appended to the end of the page.
## Response
Will be "success" for successful requests
Total number of blocks that were appended
Number of internal Notion API requests made (for transparency - does NOT affect your usage quota)
Number of retry attempts due to rate limiting
ID of the last block that was created (useful for subsequent appends)
Array of warning messages when content modifications are made:
* URL truncation notifications (when URLs exceed 2000 characters)
* Equation truncation notifications (when equations exceed 1000 characters)
## Examples
```bash curl theme={null}
curl -X POST "https://api.mark2notion.com/api/append" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"markdown": "# New Section\n\nThis content will be appended to my Notion page.\n\n- Item 1\n- Item 2",
"pageId": "https://notion.so/Your-Page-Title-a1b2c3d4e5f67890abcdef1234567890"
}'
```
```javascript JavaScript theme={null}
const response = await fetch('https://api.mark2notion.com/api/append', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
markdown: `# New Section
This content will be appended to my Notion page.
- Item 1
- Item 2`,
pageId: 'https://notion.so/Your-Page-Title-a1b2c3d4e5f67890abcdef1234567890'
})
});
const data = await response.json();
console.log(`Added ${data.data.totalBlocks} blocks`);
```
```python Python theme={null}
import requests
response = requests.post(
'https://api.mark2notion.com/api/append',
headers={
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
json={
'markdown': '''# New Section
This content will be appended to my Notion page.
- Item 1
- Item 2''',
'pageId': 'https://notion.so/Your-Page-Title-a1b2c3d4e5f67890abcdef1234567890'
}
)
data = response.json()
print(f"Added {data['data']['totalBlocks']} blocks")
```
```json Standard Response theme={null}
{
"status": "success",
"data": {
"totalBlocks": 4,
"requestCount": 1,
"retryCount": 0,
"lastBlockId": "f9e8d7c6-b5a4-3210-9876-543210fedcba"
}
}
```
```json Standard Response (Large Content) theme={null}
{
"status": "success",
"data": {
"totalBlocks": 1247,
"requestCount": 3,
"retryCount": 1,
"lastBlockId": "f9e8d7c6-b5a4-3210-9876-543210fedcba"
}
}
```
```json Response with Content Truncation theme={null}
{
"status": "success",
"data": {
"totalBlocks": 15,
"requestCount": 1,
"retryCount": 0,
"lastBlockId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"warnings": [
"Content truncated due to Notion API limits:",
"โข 2 URLs truncated to 2000 characters",
"โข 1 equation truncated to 1000 characters"
]
}
}
```
```json Response with Deep Nesting theme={null}
{
"status": "success",
"data": {
"totalBlocks": 87,
"requestCount": 4,
"retryCount": 0,
"lastBlockId": "xyz789-abc123-def456-ghi789"
}
}
```
## Append Positioning
### Default Behavior
By default, content is appended to the end of the page.
### Using the `after` Parameter
Specify a block ID to append content after a specific block:
```json theme={null}
{
"markdown": "# New content",
"pageId": "https://notion.so/Your-Page-Title-abc123",
"after": "block-id-to-append-after"
}
```
### Chaining Appends
Use the `lastBlockId` from the response to chain multiple append operations:
```javascript theme={null}
// First append
const firstAppend = await appendToNotion({
markdown: "# First section",
// ... other params
});
// Second append after the first
const secondAppend = await appendToNotion({
markdown: "# Second section",
after: firstAppend.data.lastBlockId,
// ... other params
});
```
## Rate Limiting & Retries
The append endpoint includes intelligent rate limiting:
* **Automatic chunking**: Large content is split into chunks of 100 blocks
* **Sequential processing**: Chunks are processed in order to maintain content sequence
* **Retry logic**: Automatic retries with exponential backoff for rate limits
* **Respectful timing**: 400ms delay between requests to respect Notion's limits
Each append API call counts as **1 usage** regardless of complexity. The `requestCount` is provided for transparency but does NOT affect your quota.
## Notion Setup
Before using the append endpoint, connect your Notion workspace in the [dashboard](https://dashboard.mark2notion.com) via OAuth. Then pass your target page as a URL or page ID in the `pageId` field.
## Error Responses
Understand error responses and how to handle them.
## Usage Notes
Every append request counts as **exactly 1 API call** in your usage quota, regardless of content size or complexity.
Make sure your Notion integration has access to the target page. The integration must be explicitly shared with the page.
## Idempotency
The append endpoint includes built-in idempotency protection:
* Duplicate requests with the same content and parameters are automatically detected
* Returns the original response for duplicate requests
* Prevents accidental duplicate content on your pages
## Notion API Limits Handling
Mark2Notion provides **comprehensive protection** against all Notion API limits with intelligent handling strategies:
### โ
**Fully Protected Limits**
* **Rich Text**: 2000 characters per block (automatic text splitting)
* **URLs**: 2000 characters (truncated with warnings if exceeded)
* **Equations**: 1000 characters (truncated with warnings if exceeded)
* **Email/Phone**: Handled as regular text content (no special limits)
* **Payload Size**: 500KB maximum per request (pre-validation with detailed errors)
* **Total Blocks**: 1000 blocks maximum (automatic splitting into manageable chunks)
* **Children Count**: 100 blocks per request (intelligent chunking)
* **Nesting Depth**: 2 levels maximum (deep nesting preserved via sub-request strategy)
* **Request Rate**: 3 requests/second (exponential backoff + 400ms delays)
* **Integration Capabilities**: Proper error handling for access issues
* **Page Access**: Automatic verification before processing
### ๐ **Advanced Capabilities**
Handles unlimited nesting depth (5, 6, 7+ levels) by breaking into sub-requests while maintaining parent-child relationships
Automatically splits documents with 1000+ blocks into manageable chunks without losing content order
Provides clear warnings when URLs or equations are truncated, so you know exactly what was modified
Every append request counts as exactly 1 API call, regardless of internal complexity
**Perfect Coverage**: Mark2Notion handles 100% of applicable Notion API limits automatically. You can send any markdown content without worrying about hitting Notion's restrictions.
# Append Prebuilt Blocks
Source: https://docs.mark2notion.com/api-reference/append-blocks
POST https://api.mark2notion.com/api/append-blocks
Append already-converted Notion blocks directly to a page
## Overview
Use the append-blocks endpoint when you already have an array of Notion block objects and simply need them inserted into a page. This endpoint skips Markdown conversion and feeds your blocks through the same intelligent planning, batching, and retry logic used by the Markdown append workflow.
## Request
Your Mark2Notion API key
Array of Notion block objects you want to append. Each block must follow the structure expected by the Notion API, including nested `children` when needed.
Your Notion integration token. Optional when your workspace is connected via OAuth in the dashboard. Pass this if you prefer to authenticate with a manual integration token instead. See [Using a Manual Notion Token](/quickstart#using-a-manual-notion-token-advanced).
The URL or page ID of the Notion page to append blocks to. Pass the full `notion.so` page URL or just the page ID โ both are accepted.
Optional block ID to append content after. If omitted, blocks are appended to the end of the page.
## Response
Will be "success" for successful requests
Total number of blocks that were appended
Number of internal Notion API requests made (for transparency - does NOT affect your usage quota)
Number of retry attempts caused by rate limiting
ID of the last block that was created (use this for subsequent `after` appends)
## Examples
```bash curl theme={null}
curl -X POST "https://api.mark2notion.com/api/append-blocks" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"blocks": [
{
"object": "block",
"type": "paragraph",
"paragraph": {
"rich_text": [
{
"type": "text",
"text": { "content": "First paragraph from raw blocks" }
}
]
}
},
{
"object": "block",
"type": "paragraph",
"paragraph": {
"rich_text": [
{
"type": "text",
"text": { "content": "Second paragraph" }
}
]
}
}
],
"pageId": "https://notion.so/Your-Page-Title-a1b2c3d4e5f67890abcdef1234567890"
}'
```
```javascript JavaScript theme={null}
const blocks = [
{
object: 'block',
type: 'paragraph',
paragraph: {
rich_text: [
{
type: 'text',
text: { content: 'First paragraph from raw blocks' }
}
]
}
},
{
object: 'block',
type: 'paragraph',
paragraph: {
rich_text: [
{
type: 'text',
text: { content: 'Second paragraph' }
}
]
}
}
];
const response = await fetch('https://api.mark2notion.com/api/append-blocks', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
blocks,
pageId: 'https://notion.so/Your-Page-Title-a1b2c3d4e5f67890abcdef1234567890'
})
});
const data = await response.json();
console.log(`Added ${data.data.totalBlocks} blocks`);
```
```python Python theme={null}
import requests
blocks = [
{
"object": "block",
"type": "paragraph",
"paragraph": {
"rich_text": [
{
"type": "text",
"text": {"content": "First paragraph from raw blocks"}
}
]
}
}
]
response = requests.post(
'https://api.mark2notion.com/api/append-blocks',
headers={
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
json={
'blocks': blocks,
'pageId': 'https://notion.so/Your-Page-Title-a1b2c3d4e5f67890abcdef1234567890'
}
)
data = response.json()
print(f"Added {data['data']['totalBlocks']} blocks")
```
```json Standard Response theme={null}
{
"status": "success",
"data": {
"totalBlocks": 2,
"requestCount": 1,
"retryCount": 0,
"lastBlockId": "f9e8d7c6-b5a4-3210-9876-543210fedcba"
}
}
```
```json Validation Error theme={null}
{
"status": "fail",
"data": {
"blocks": "Blocks must be a non-empty array"
}
}
```
## Usage Notes
* Provide blocks exactly as expected by the Notion API. Complex structures (tables, synced blocks, nested children) are supported as long as the JSON matches Notion's schema.
* The endpoint enforces non-empty arrays and idempotency, so repeated requests with the same blocks are safely deduplicated.
* Use the `after` parameter together with the `lastBlockId` returned from previous calls to chain precise insertions.
* If you need help generating blocks, use the [`/convert`](./convert) endpoint first and then pass the resulting array here.
# Clear Notion Page
Source: https://docs.mark2notion.com/api-reference/clear-page
POST https://api.mark2notion.com/api/clear-page
Archive all top-level blocks from a Notion page
## Overview
The clear-page endpoint archives all top-level content blocks from a Notion page, effectively clearing it. This is useful for:
* Resetting a page before adding new content
* Cleaning up test or temporary pages
* Automating page content replacement workflows
**Important Notes**:
* Uses Notion's archive functionality (blocks can be recovered from trash)
* Only deletes top-level blocks; child blocks are automatically archived with their parents
* Does NOT delete the page itself, only its content
* Preserves page properties and title
## Request
Your Mark2Notion API key
Your Notion integration token. Optional when your workspace is connected via OAuth in the dashboard. Pass this if you prefer to authenticate with a manual integration token instead. See [Using a Manual Notion Token](/quickstart#using-a-manual-notion-token-advanced).
The URL or page ID of the Notion page to clear. Pass the full `notion.so` page URL or just the page ID โ both are accepted.
## Response
Will be "success" for successful requests
Total number of top-level blocks that were archived
Number of retry attempts due to rate limiting or transient errors
## Examples
```bash curl theme={null}
curl -X POST "https://api.mark2notion.com/api/clear-page" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"pageId": "https://notion.so/Your-Page-Title-a1b2c3d4e5f67890abcdef1234567890"
}'
```
```javascript JavaScript theme={null}
const response = await fetch('https://api.mark2notion.com/api/clear-page', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
pageId: 'https://notion.so/Your-Page-Title-a1b2c3d4e5f67890abcdef1234567890'
})
});
const data = await response.json();
console.log(`Cleared ${data.data.blocksDeleted} blocks`);
```
```python Python theme={null}
import requests
response = requests.post(
'https://api.mark2notion.com/api/clear-page',
headers={
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
json={
'pageId': 'https://notion.so/Your-Page-Title-a1b2c3d4e5f67890abcdef1234567890'
}
)
data = response.json()
print(f"Cleared {data['data']['blocksDeleted']} blocks")
```
```go Go theme={null}
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
payload := map[string]string{
"pageId": "https://notion.so/Your-Page-Title-a1b2c3d4e5f67890abcdef1234567890",
}
jsonData, _ := json.Marshal(payload)
req, _ := http.NewRequest(
"POST",
"https://api.mark2notion.com/api/clear-page",
bytes.NewBuffer(jsonData),
)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("x-api-key", "YOUR_API_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
data := result["data"].(map[string]interface{})
fmt.Printf("Cleared %.0f blocks\n", data["blocksDeleted"])
}
```
## Response Example
```json theme={null}
{
"status": "success",
"data": {
"blocksDeleted": 42,
"retryCount": 0
}
}
```
## Common Use Cases
### Clear and Replace Page Content
Combine with the `/append` endpoint to replace page content:
```javascript theme={null}
// 1. Clear existing content
await fetch('https://api.mark2notion.com/api/clear-page', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
pageId: 'https://notion.so/Your-Page-Title-abc123'
})
});
// 2. Add new content
await fetch('https://api.mark2notion.com/api/append', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
markdown: '# Fresh Content\n\nThis replaces everything.',
pageId: 'https://notion.so/Your-Page-Title-abc123'
})
});
```
### Automated Report Generation
Clear and regenerate daily reports:
```python theme={null}
import requests
from datetime import datetime
# Clear yesterday's report
requests.post(
'https://api.mark2notion.com/api/clear-page',
headers={'x-api-key': 'YOUR_API_KEY'},
json={
'pageId': 'https://notion.so/Your-Report-Page-abc123'
}
)
# Generate today's report
report_markdown = f"# Daily Report - {datetime.now().strftime('%Y-%m-%d')}\n\n..."
requests.post(
'https://api.mark2notion.com/api/append',
headers={'x-api-key': 'YOUR_API_KEY'},
json={
'markdown': report_markdown,
'pageId': 'https://notion.so/Your-Report-Page-abc123'
}
)
```
## Error Handling
The endpoint follows standard error responses. See the [Errors](/errors) page for details.
### Common Errors
| Status | Meaning |
| ------ | ------------------------------------------------------------------------------------------------ |
| `400` | Missing or invalid `pageId` parameter |
| `401` | Invalid Notion token or no access to the specified page |
| `403` | Invalid API key |
| `404` | Page does not exist or has been deleted |
| `429` | Too many requests. Automatic retry logic is built in, but very high volumes may still hit limits |
## Usage & Pricing
Each successful clear-page request counts as **1 API usage** regardless of how many blocks are deleted.
* Empty pages (0 blocks): Still counts as 1 usage
* Pages with many blocks: Still counts as 1 usage
* Failed requests: Do not count towards usage
**Pro Tip**: Since clearing a page costs 1 credit regardless of size, it's efficient for pages with lots of content. Use this when you need a clean slate!
## Idempotency
The clear-page endpoint implements idempotency to prevent duplicate operations:
* Concurrent identical requests return `202 Accepted` with "in\_progress" status
* Once completed, subsequent clear requests are processed normally
* Each request is tracked based on API key, page ID, and Notion token
## Performance
* **Average response time**: 2-5 seconds for typical pages
* **Large pages** (100+ blocks): Up to 10-15 seconds
* The endpoint processes blocks sequentially with built-in rate limit handling
* Automatic retries ensure reliability even during Notion API throttling
## Integration Examples
### n8n Workflow
Create a workflow node that clears a page before updating:
1. HTTP Request node โ `POST /api/clear-page`
2. Wait 2 seconds (optional, for safety)
3. HTTP Request node โ `POST /api/append` with new content
### Make (Integromat)
Add a "Clear Page" action:
1. HTTP module โ Make a request
2. Method: POST
3. URL: `https://api.mark2notion.com/api/clear-page`
4. Headers: `x-api-key` with your API key
5. Body: JSON with `pageId`
### Zapier
Use the Webhooks by Zapier action:
1. Choose "POST" method
2. URL: `https://api.mark2notion.com/api/clear-page`
3. Add header: `x-api-key`
4. Payload Type: JSON
5. Add data: `pageId` (URL or page ID)
# Convert Markdown
Source: https://docs.mark2notion.com/api-reference/convert
POST https://api.mark2notion.com/api/convert
Convert Markdown text to Notion block objects
## 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**: `colored text` (supports 9 Notion colors)
* **Links**: `[text](url)` and `` autolinks
* **Images**: ``
### 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 `___`
* **Toggle Blocks**: HTML `` and `` tags for collapsible sections
### HTML Color Support
Add colors to your text using standard HTML syntax:
```markdown theme={null}
This is red text and blue text.
```
**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:**
```markdown theme={null}
# Heading with purple text
Paragraph with **bold red** text.
- List item with green text
```
### Toggle Blocks (Collapsible Sections)
Create collapsible toggle blocks using HTML `` and `` tags:
```markdown theme={null}
Click to expand
Content inside the toggle block can include:
- Headings
- Lists
- Paragraphs
- Any other Markdown elements
```
**Features:**
* Summary text supports **bold** (`` or ``) and *italic* (`` or ``) formatting
* Content can include any Markdown elements (headings, lists, code blocks, etc.)
* Nested details blocks are not supported
* Malformed HTML is silently ignored
**Examples:**
```markdown theme={null}
Email Summary
## Section 1 Title
- Bullet point 1
- Bullet point 2
## Section 2 Title
- Another bullet point
```
```markdown theme={null}
Optional Settings
Configure advanced options here.
```
### Generated Notion Block Types
| Markdown Element | Notion Block Type | Notes |
| ---------------- | ------------------------------------- | ---------------------------------- |
| `# Heading` | `heading_1`, `heading_2`, `heading_3` | H4-H6 map to heading\_3 |
| `Text` | `paragraph` | With rich text formatting |
| `- Item` | `bulleted_list_item` | Unlimited nesting |
| `1. Item` | `numbered_list_item` | Unlimited nesting |
| ` ```code``` ` | `code` | With language support |
| `> Quote` | `quote` | Standard blockquotes |
| `> [!NOTE]` | `callout` | With icons and colors |
| `` | `image` | External images |
| `\| Table \|` | `table` | With headers |
| `---` | `divider` | Horizontal rules |
| `` | `toggle` | Collapsible sections with children |
## 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
```json theme={null}
{
"type": "paragraph",
"paragraph": {
"rich_text": [
{
"type": "text",
"text": { "content": "First 2000 characters of content..." }
},
{
"type": "text",
"text": { "content": "...remaining characters continue here" }
}
]
}
}
```
## Request
Your Mark2Notion API key
The Markdown content to convert to Notion blocks
## Response
Will be "success" for successful requests
Array of Notion block objects ready for use with Notion API
Total number of blocks generated
## Examples
````bash curl theme={null}
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```"
}'
````
```javascript JavaScript theme={null}
const response = await fetch('https://api.mark2notion.com/api/convert', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
markdown: `# My Heading
This is a **bold** paragraph with a [link](https://example.com).
> [!NOTE]
> This is a GitHub-flavored alert that becomes a callout!
- List item 1
- List item 2
---
## Code Example
\`\`\`javascript
console.log("Hello World!");
\`\`\``
})
});
const data = await response.json();
console.log(data.data.blocks);
```
````python Python theme={null}
import requests
response = requests.post(
'https://api.mark2notion.com/api/convert',
headers={
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
json={
'markdown': '''# My Heading
This is a **bold** paragraph with a [link](https://example.com).
> [!NOTE]
> This is a GitHub-flavored alert that becomes a callout!
- List item 1
- List item 2
---
## Code Example
```javascript
console.log("Hello World!");
```'''
}
)
data = response.json()
print(data['data']['blocks'])
````
```json Example Response theme={null}
{
"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
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.
# API Reference
Source: https://docs.mark2notion.com/api-reference/introduction
Complete reference for all Mark2Notion API endpoints
## Available Endpoints
Mark2Notion provides a simple REST API for converting Markdown to Notion blocks and managing Notion page content.
### Content Creation & Management
Convert Markdown text to Notion block JSON without touching Notion
Convert Markdown and append it directly to a Notion page
Append pre-converted Notion blocks to a page
Archive all content blocks from a Notion page
### Content Extraction
Extract content from a Notion page and convert it to Markdown
## Authentication
All API endpoints require authentication using an API key passed in the `x-api-key` header:
```bash theme={null}
curl -X POST "https://api.mark2notion.com/api/convert" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"markdown": "# Hello World"}'
```
Get your API key from the [Mark2Notion dashboard](https://mark2notion.com).
## Common Workflows
### Replace Page Content
Clear and update a page in one workflow:
```javascript theme={null}
// 1. Clear existing content
await fetch('https://api.mark2notion.com/api/clear-page', {
method: 'POST',
headers: { 'x-api-key': 'YOUR_KEY' },
body: JSON.stringify({
pageId: 'https://notion.so/Your-Page-Title-abc123'
})
});
// 2. Add fresh content
await fetch('https://api.mark2notion.com/api/append', {
method: 'POST',
headers: { 'x-api-key': 'YOUR_KEY' },
body: JSON.stringify({
markdown: '# New Content',
pageId: 'https://notion.so/Your-Page-Title-abc123'
})
});
```
### Convert Once, Append Multiple Times
Optimize by converting once and appending to multiple pages:
```javascript theme={null}
// 1. Convert Markdown to blocks
const convertRes = await fetch('https://api.mark2notion.com/api/convert', {
method: 'POST',
headers: { 'x-api-key': 'YOUR_KEY' },
body: JSON.stringify({ markdown: '# Report\n\nData here...' })
});
const { blocks } = (await convertRes.json()).data;
// 2. Append to multiple pages
for (const pageId of ['page1', 'page2', 'page3']) {
await fetch('https://api.mark2notion.com/api/append-blocks', {
method: 'POST',
headers: { 'x-api-key': 'YOUR_KEY' },
body: JSON.stringify({
blocks,
pageId
})
});
}
```
## Rate Limits
All endpoints include automatic retry logic and respect Notion's rate limits. The API handles:
* Rate limit responses (429)
* Transient network errors
* Notion API throttling
You don't need to implement retry logic in your code - it's handled automatically.
## Need Help?
* **Issues & Bugs**: [GitHub Issues](https://github.com/elitemaks/mark2notion-api/issues)
* **Errors**: See the [Errors](/errors) page for common error codes
* **Feedback**: Share your experience on the [Feedback](/feedback) page
# Notion to Markdown
Source: https://docs.mark2notion.com/api-reference/notion-to-markdown
POST https://api.mark2notion.com/api/notion-to-markdown
Convert Notion page content to Markdown format
## 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 `` 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
### Text Formatting & Colors
All rich text formatting from Notion is preserved in the Markdown output:
* **Bold**: Converted to `**bold**`
* **Italic**: Converted to `*italic*`
* **Code**: Converted to `` `code` ``
* **Strikethrough**: Converted to `~~strikethrough~~`
* **Links**: Converted to `[text](url)`
* **Colors**: Converted to HTML `` tags with inline styles
**Color Support:**
Notion text colors are converted to HTML spans with inline CSS styles. This allows the colors to be preserved when the Markdown is rendered in systems that support HTML.
**Supported Colors:**
* `red`, `blue`, `green`, `yellow`, `orange`, `purple`, `pink`, `gray`, `brown`
**Example:**
```markdown theme={null}
This is red text and blue text.
```
**Features:**
* Works with all block types (paragraphs, headings, lists, quotes, etc.)
* Can be combined with other formatting (bold, italic, code, etc.)
* Multiple colors can be used within a single block
**Limitations:**
* Background colors (e.g., `red_background`) are not currently supported
* Colors are exported as HTML, which requires the Markdown renderer to support inline HTML
## Request
Your Mark2Notion API key
Your Notion integration token. Optional when your workspace is connected via OAuth in the dashboard. Pass this if you prefer to authenticate with a manual integration token instead. See [Using a Manual Notion Token](/quickstart#using-a-manual-notion-token-advanced).
The URL or page ID of the Notion page to convert. Pass the full `notion.so` page URL or just the page ID โ both are accepted.
## Response
Will be "success" for successful requests
An object containing the Markdown representation of the page content
The Markdown content of the main/parent page
If the page has child pages, each child page will be included as a separate property with the child page title as the key and its Markdown content as the value
The ID of the page that was converted
## Examples
```bash curl theme={null}
curl -X POST "https://api.mark2notion.com/api/notion-to-markdown" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"pageId": "https://notion.so/Your-Page-Title-abc123def456"
}'
```
```javascript JavaScript theme={null}
const response = await fetch('https://api.mark2notion.com/api/notion-to-markdown', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
pageId: 'https://notion.so/Your-Page-Title-abc123def456'
})
});
const data = await response.json();
console.log(data.data.markdown.parent); // Parent page content
// If there are child pages, they'll be available as separate properties:
// console.log(data.data.markdown['Child Page Name']);
```
```python Python theme={null}
import requests
response = requests.post(
'https://api.mark2notion.com/api/notion-to-markdown',
headers={
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
json={
'pageId': 'https://notion.so/Your-Page-Title-abc123def456'
}
)
data = response.json()
print(data['data']['markdown']['parent']) # Parent page content
# If there are child pages, they'll be available as separate keys:
# print(data['data']['markdown']['Child Page Name'])
```
````json Example Response (Simple Page) theme={null}
{
"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"
}
}
````
```json Example Response (Page with Child Pages) theme={null}
{
"status": "success",
"data": {
"markdown": {
"parent": "# Main Page\n\nThis is the parent page content.\n\n> ๐ Note\n> This is a callout\n",
"Child Page 1": "## Child Page Content\n\nThis is content from the first child page.\n",
"Another Child": "## Another Child Page\n\nContent from another child page.\n"
},
"pageId": "abc123def456"
}
}
```
## Error Responses
Understand error responses and how to handle them.
### Common Errors
**Status Code**: 401 Unauthorized
The Notion token provided is invalid or expired. Make sure you're using a valid integration token.
**Status Code**: 404 Not Found
The 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 Forbidden
Your 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 workspace is connected in the dashboard and has access to the page you want to convert.
## Setup Guide
Connect your Notion workspace in the [dashboard](https://dashboard.mark2notion.com) via OAuth. Then pass your target page as a URL or page ID in the `pageId` field โ no manual integration tokens required.
## 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
# Authentication
Source: https://docs.mark2notion.com/authentication
How to authenticate your requests and manage API usage
## API Key Authentication
Mark2Notion uses API key authentication. Include your API key in the `x-api-key` header for all requests.
```bash curl theme={null}
curl -X POST "https://api.mark2notion.com/api/convert" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"markdown": "# Test"}'
```
```javascript JavaScript theme={null}
const headers = {
'x-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
};
```
```python Python theme={null}
headers = {
'x-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
}
```
## Getting Your API Key
1. **Sign up** at [mark2notion.com](https://mark2notion.com)
2. **Navigate** to your dashboard
3. **Copy** your API key from the API section
4. **Keep it secure** - never expose it in client-side code
Your API key is sensitive. Never include it in client-side code or commit it to version control.
## Usage Limits
API usage is tracked and limited based on your subscription plan.
You can check usage in the [dashbard](https://dashboard.mark2notion.com)
### Rate Limiting
The API implements intelligent rate limiting:
* **Respect Notion's limits**: 3 requests per second to Notion API
* **Automatic retries**: Built-in exponential backoff for rate limits
* **Usage tracking**: Real-time tracking of your quota usage
## Error Responses
### Authentication Errors
```json 401 - Missing API Key theme={null}
{
"status": "error",
"message": "Missing x-api-key"
}
```
```json 403 - Invalid API Key theme={null}
{
"status": "error",
"message": "Invalid API key"
}
```
```json 429 - Usage Limit Exceeded theme={null}
{
"status": "error",
"message": "Usage quota exceeded for current billing period",
"data": {
"current_usage": 1000,
"quota": 1000,
"plan": "free",
"requests_remaining": 0
}
}
```
## Best Practices
**Secure Storage**: Store your API key in environment variables, not in your code.
**Monitor Usage**: Check the usage headers to avoid hitting limits unexpectedly.
**Handle Errors**: Always implement proper error handling for authentication failures.
## Example: Secure Implementation
```javascript JavaScript theme={null}
// โ
Good - using environment variable
const apiKey = process.env.MARK2NOTION_API_KEY;
// โ Bad - hardcoded API key
const apiKey = "mk_live_abcd1234...";
```
```python Python theme={null}
import os
# โ
Good - using environment variable
api_key = os.getenv('MARK2NOTION_API_KEY')
# โ Bad - hardcoded API key
api_key = "mk_live_abcd1234..."
```
# Open Source Credits
Source: https://docs.mark2notion.com/credits
# Open Source Licenses
Mark2Notion uses the following open source software:
## Martian
Markdown to Notion conversion library\
**License:** MIT\
**Copyright:** ยฉ 2022 Instantish, Inc.\
**Repository:** [github.com/tryfabric/martian](https://github.com/tryfabric/martian)
View MIT License
Copyright (c) 2022 Instantish, Inc.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
## notion-to-md
Notion to Markdown conversion library\
**License:** MIT\
**Copyright:** ยฉ 2021 Souvik Kar Mahapatra\
**Repository:** [github.com/souvikinator/notion-to-md](https://github.com/souvikinator/notion-to-md)
View MIT License
Copyright (c) 2021 Souvik Kar Mahapatra
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
# Error Handling
Source: https://docs.mark2notion.com/errors
Understanding and handling Mark2Notion API errors
## Error Response Format
All Mark2Notion API errors follow a consistent format to help you handle them programmatically.
## Response Types
### Success Response
```json theme={null}
{
"status": "success",
"data": {
// Response data
}
}
```
### Validation Errors (400)
Used when request parameters are invalid or missing.
```json theme={null}
{
"status": "fail",
"data": {
"field_name": "Error description for this field",
"another_field": "Another validation error"
}
}
```
### Authentication Errors (401, 403)
```json theme={null}
{
"status": "error",
"message": "Authentication error description"
}
```
### Rate Limit Errors (429)
```json theme={null}
{
"status": "error",
"message": "Usage quota exceeded for current billing period",
"data": {
"current_usage": 1000,
"quota": 1000,
"plan": "free",
"requests_remaining": 0
}
}
```
### Server Errors (500)
```json theme={null}
{
"status": "error",
"message": "Internal server error description"
}
```
## Common Error Scenarios
### Authentication Issues
**Cause**: No `x-api-key` header provided
**Solution**: Include your API key in the request headers
```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
"https://api.mark2notion.com/api/convert"
```
**Cause**: API key is invalid, expired, or deactivated
**Solution**:
* Check your API key in the dashboard
* Generate a new API key if needed
* Ensure your subscription is active
**Cause**: Your subscription is inactive or cancelled
**Solution**: Reactivate your subscription in the dashboard
### Usage Limits
**Cause**: You've exceeded your monthly request quota
**Solution**:
* Wait for your quota to reset next month
* Upgrade to a higher plan
* Monitor usage with response headers
**Headers to monitor**:
```
X-Usage-Current: 950
X-Usage-Quota: 1000
X-Usage-Remaining: 50
```
### Notion-Related Errors
**Error**: `"Invalid Notion token or insufficient permissions"`
**Solution**:
1. First, check that your Notion workspace is connected in the [dashboard](https://dashboard.mark2notion.com) โ reconnect if needed
2. If using a manual `notionToken`, verify it's still active at [notion.so/my-integrations](https://notion.so/my-integrations)
3. Ensure the integration has access to the target workspace
**Error**: `"Page not found or access denied"`
**Causes**:
* Page URL or ID is incorrect
* Page has been deleted
* Notion connection doesn't have access to the page
**Solution**:
1. First, check that your Notion workspace is connected in the [dashboard](https://dashboard.mark2notion.com) and that the connected account has access to this page (or its parent)
2. Verify the page URL or ID is correct (copy directly from Notion)
3. If using a manual `notionToken`, share the page with your integration via **ยทยทยท** โ **Connections**
### Content Validation
**Error**: `{"status": "fail", "data": {"markdown": "Missing or invalid markdown content"}}`
**Causes**:
* Empty markdown string
* Markdown parameter missing
* Content too large
**Solution**: Provide valid markdown content in the request body
## Error Handling Best Practices
### 1. Check Response Status
Always check the HTTP status code and response status field:
```javascript JavaScript theme={null}
const response = await fetch('/api/convert', {
// ... request options
});
if (!response.ok) {
const error = await response.json();
switch (response.status) {
case 400:
// Handle validation errors
console.log('Validation errors:', error.data);
break;
case 401:
case 403:
// Handle authentication errors
console.log('Auth error:', error.message);
break;
case 429:
// Handle rate limiting
console.log('Rate limited:', error.data);
break;
default:
console.log('Unexpected error:', error.message);
}
return;
}
const data = await response.json();
// Handle success
```
```python Python theme={null}
import requests
try:
response = requests.post('/api/convert', json=data)
response.raise_for_status() # Raises exception for 4xx/5xx
result = response.json()
# Handle success
except requests.HTTPError as e:
error_data = e.response.json()
if e.response.status_code == 400:
# Handle validation errors
print("Validation errors:", error_data['data'])
elif e.response.status_code in [401, 403]:
# Handle authentication
print("Auth error:", error_data['message'])
elif e.response.status_code == 429:
# Handle rate limiting
print("Rate limited:", error_data['data'])
else:
print("Unexpected error:", error_data['message'])
```
### 2. Implement Retry Logic
For rate limiting and transient errors:
```javascript theme={null}
async function callAPIWithRetry(apiCall, maxRetries = 3) {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
const response = await apiCall();
if (response.status === 429) {
// Rate limited - wait and retry
const waitTime = Math.pow(2, attempt) * 1000; // Exponential backoff
await new Promise(resolve => setTimeout(resolve, waitTime));
continue;
}
return response;
} catch (error) {
if (attempt === maxRetries) throw error;
// Wait before retrying
await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
}
}
}
```
### 3. Monitor Usage
Track your API usage to avoid hitting limits:
```javascript theme={null}
function logUsageInfo(response) {
const usage = {
current: response.headers.get('X-Usage-Current'),
quota: response.headers.get('X-Usage-Quota'),
remaining: response.headers.get('X-Usage-Remaining'),
plan: response.headers.get('X-Usage-Plan')
};
console.log('API Usage:', usage);
// Warn when approaching limit
if (usage.remaining < usage.quota * 0.1) {
console.warn('Approaching usage limit!');
}
}
```
### 4. Graceful Degradation
Handle errors gracefully in your application:
```javascript theme={null}
async function convertMarkdown(markdown) {
try {
const response = await callAPI('/api/convert', { markdown });
return response.data.blocks;
} catch (error) {
// Log error for debugging
console.error('Markdown conversion failed:', error);
// Return fallback or throw user-friendly error
throw new Error('Unable to convert markdown at this time. Please try again later.');
}
}
```
## Getting Help
If you encounter errors not covered here:
Report bugs or unexpected behavior
Share your experience and suggestions
When reporting issues, include the full error response and the request that caused it (without sensitive data like API keys).
# Feedback & Support
Source: https://docs.mark2notion.com/feedback
Help us improve Mark2Notion API
## We Want Your Feedback!
Your feedback helps us build a better API. Whether you've found a bug, have a feature request, or just want to share your experience, we'd love to hear from you.
## Quick Feedback
Use the feedback buttons at the bottom of each documentation page to quickly rate content and suggest improvements.
## Report Issues
Found a bug or unexpected behavior? Please report it so we can fix it quickly.
Create a detailed bug report or feature request on GitHub
### What to Include in Bug Reports
To help us resolve issues quickly, please include:
* HTTP method and endpoint
* Request headers (without API key)
* Request body (sample data)
* Expected vs actual behavior
* Full error response
* HTTP status code
* Timestamp when the error occurred
* Frequency (one-time or recurring)
* Programming language/framework
* SDK version (if applicable)
* Operating system
* Any relevant code snippets
### Example Bug Report
**Describe the bug**\
The append endpoint returns a 500 error when appending large markdown content (>5000 characters).
**Request**
```http theme={null}
POST /api/append
Headers: x-api-key: [REDACTED]
Body: {
"markdown": "[large content here]",
"pageId": "abc123..."
}
```
**Error Response**
```json theme={null}
{
"status": "error",
"message": "Internal server error"
}
```
**Expected Behavior**\
Content should be successfully appended to the Notion page.
**Environment**
* Language: JavaScript/Node.js
* OS: macOS 14.1
* Content size: \~6000 characters
## Feature Requests
Have an idea for improving the API? We'd love to hear it!
Suggest new features or improvements
Discuss API improvements and integrations
## Response Times
We aim to respond to all feedback within:
* ๐ **Bug reports**: 24-48 hours
* ๐ก **Feature requests**: 3-5 days
* ๐ **Documentation issues**: 1-2 days
* ๐ฌ **General feedback**: 2-3 days
Response times may be longer during weekends and holidays.
## Thank You!
Your feedback is invaluable in making Mark2Notion API better for everyone. Every bug report, feature request, and suggestion helps us build something amazing.
## Quick Links
Something's not working as expected
Suggest a new feature or improvement
Help make the documentation better
Share ideas and discuss use cases
# Mark2Notion API
Source: https://docs.mark2notion.com/index
Convert and append Markdown content to Notion pages with a simple API
## Key Features
Transform Markdown text into Notion block objects that you can use anywhere.
Directly append Markdown content to existing Notion pages with smart positioning.
Archive all blocks from a page to start fresh or automate content replacement.
Built-in rate limiting and retry logic to respect Notion's API limits.
Automatically respects Notion's character and block limits - your Markdown always gets delivered safely.
## Getting Started
Get up and running with Mark2Notion in minutes:
Make your first API call and see the magic happen.
Learn how to authenticate your requests with API keys.
## Need Help?
Found a bug or have a feature request? Let us know!
Help us improve by sharing your experience.
## Open Source
Mark2Notion is built with open source software. [View open source credits โ](/credits)
# Quickstart
Source: https://docs.mark2notion.com/quickstart
Start using Mark2Notion API in under 5 minutes
## Get Your API Key
First, you'll need to get your API key from the Mark2Notion dashboard.
Visit [mark2notion.com](https://mark2notion.com) and create an account.
Navigate to your dashboard and copy your API key.
Click "Connect Notion" in your [dashboard](https://dashboard.mark2notion.com) to authorize access to your workspace via OAuth. Required for `/append`, `/append-blocks`, `/clear-page`, and `/notion-to-markdown`.
## Get the Page URL or ID
Pass a URL or page ID as the `pageId` parameter:
* Full Notion page URL: `https://notion.so/Your-Page-Title-abc123def456`
* Or just the page ID: `abc123def456`
Both formats are accepted โ the API normalizes them automatically.
## Using a Manual Notion Token (Advanced)
If you prefer not to use OAuth, you can pass a `notionToken` directly in each request instead.
Go to [notion.so/my-integrations](https://notion.so/my-integrations), click "New integration", select your workspace, and copy the Internal Integration Token (starts with `ntn_`).
Open your Notion page, click the **ยทยทยท** menu โ **Connections** โ **Add connection**, then select your integration. Repeat for each page you want to access.
Include `notionToken` in your request body alongside `pageId`. The OAuth connection is not needed when a token is provided directly.
## Make Your First Request
Let's convert some Markdown to Notion blocks:
```bash curl theme={null}
curl -X POST "https://api.mark2notion.com/api/convert" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"markdown": "# Hello World\n\nThis is my **first** API call!"
}'
```
```javascript JavaScript theme={null}
const response = await fetch('https://api.mark2notion.com/api/convert', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
markdown: '# Hello World\n\nThis is my **first** API call!'
})
});
const data = await response.json();
console.log(data);
```
```python Python theme={null}
import requests
response = requests.post(
'https://api.mark2notion.com/api/convert',
headers={
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
json={
'markdown': '# Hello World\n\nThis is my **first** API call!'
}
)
data = response.json()
print(data)
```
## Try with Postman
Prefer using Postman? We've got you covered with a ready-to-use collection:
Visit our [Postman collection](https://www.postman.com/mark2notion-1/m2n-workspace/collection/47892602-d93cd1d2-e8ee-4eee-a8b3-4e4e14cec3a1/?action=share\&creator=47892602) on the Postman API Network and fork it to your workspace.
Click **"Watch"** on the collection to get notified when we add new endpoints and examples.
Set your Mark2Notion API key in the collection's environment variables.
## Expected Response
```json theme={null}
{
"status": "success",
"data": {
"blocks": [
{
"type": "heading_1",
"heading_1": {
"rich_text": [
{
"type": "text",
"text": {
"content": "Hello World"
}
}
]
}
},
{
"type": "paragraph",
"paragraph": {
"rich_text": [
{
"type": "text",
"text": {
"content": "This is my "
}
},
{
"type": "text",
"text": {
"content": "first"
},
"annotations": {
"bold": true
}
},
{
"type": "text",
"text": {
"content": " API call!"
}
}
]
}
}
],
"blockCount": 2
}
}
```
## Next Steps
Now that you've made your first request, you can:
Learn how to append content directly to Notion pages.
Understand error responses and how to handle them.
Learn more about API authentication and rate limits.
Share your experience and help us improve.
# Troubleshooting
Source: https://docs.mark2notion.com/troubleshooting
Common issues and solutions for Mark2Notion API
This guide covers the most common issues users encounter when using the Mark2Notion API. Each section includes the error message, what causes it, and how to fix it.
## Table Conversion Issues
### Table Cell Count Mismatch
**Error Message**:
```
Content creation Failed. Fix the following:
Number of cells in table row must match the table width of the parent table
```
**What This Means**:
Your markdown table has rows with inconsistent numbers of columns. Notion requires all rows in a table to have the same number of cells.
**Common Causes**:
* Missing pipe separators (`|`) in markdown table rows
* Extra or missing cells in some rows
* Malformed table syntax with inconsistent column counts
* Copy-pasted tables from other sources with formatting issues
**Solutions**:
1. **Check your markdown table syntax**:
```markdown theme={null}
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| A | B | C |
| D | E |
| F | G | H | I |
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| A | B | C |
| D | E | F |
| G | H | I |
```
2. **Validate your table before sending**:
* Count the number of `|` separators in each row
* Ensure header, separator, and all data rows have the same column count
* Use a markdown editor with table validation
3. **Handle empty cells properly**:
```markdown theme={null}
| Name | Email | Phone |
|----------|------------------|-------|
| John | john@example.com | 555-1234 |
| Jane | jane@example.com | |
```
**Working with AI-generated content?** If you're using AI tools (like ChatGPT, Claude, or other LLMs) to generate markdown, add this instruction to your prompt:
"Ensure all markdown tables are properly formatted with an equal number of columns in each row."
This helps prevent table formatting errors before they reach the API.
## Page and Block Access Issues
### Invalid Page ID Format
**Error Message**:
```
path failed validation: path.page_id should be a valid uuid,
instead was "1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p"
```
**What This Means**:
The page ID you provided is not in the correct UUID format. Notion page IDs must be properly formatted UUIDs with hyphens.
**Common Causes**:
* Copying page ID from URL without hyphens
* Using the page title or slug instead of ID
* Including quotes or extra characters around the ID
* Passing `"null"` or `""` as the page ID
**Solutions**:
1. **Easiest: pass the full Notion page URL** โ the API normalizes it automatically:
```
"pageId": "https://notion.so/My-Page-1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p"
```
2. **Or pass just the page ID** (with or without hyphens):
* Copy the 32-character ID from the end of the page URL
* Example with hyphens: `1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p`
* Example without hyphens: `1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p`
3. **Don't use these as page IDs**:
* โ Page titles: `"My-Multi-Category-Document"`
* โ Literal strings: `"null"`, `""`
### Page or Block Not Found
**Error Message**:
```
Could not find page with ID: 12345678-1234-1234-1234-123456789abc.
Make sure the relevant pages and databases are shared with your integration.
```
**What This Means**:
Your Notion integration doesn't have access to the page, or the page doesn't exist.
**Common Causes**:
* Page not shared with your integration
* Page was deleted or moved
* Using an old/expired page ID
* Wrong workspace (integration in different workspace than page)
* Page is in a private database
**Solutions**:
1. **Check your Notion connection in the [dashboard](https://dashboard.mark2notion.com)**:
* Make sure your Notion workspace is connected via OAuth
* The connected account must have access to the target page or its parent page/database
* Try reconnecting if you recently moved or restructured pages
2. **Verify the page exists**:
* Try opening the page URL in your browser
* Check if the page was recently deleted or archived
* Confirm you're in the correct workspace
3. **If using a manual `notionToken`**:
* Share the page with your integration via **ยทยทยท** โ **Connections** โ **Add connection**
* For pages in databases, share the entire database โ individual pages inherit access
4. **Check integration permissions**:
* Go to [notion.so/my-integrations](https://notion.so/my-integrations)
* Verify the integration is active and has "Content" capabilities
If you just shared a page with your integration, wait a few seconds before making API requests. Notion may need a moment to propagate permissions.
### Block ID Used Instead of Page ID
**Error Message**:
```
Provided ID abcd1234-5678-90ef-abcd-ef1234567890 is a block, not a page.
Use the retrieve block API instead
```
**What This Means**:
You're trying to use a block ID in the `pageId` parameter. All endpoints require a page ID, not a block ID.
**Solutions**:
1. **Use the parent page ID**:
* Get the ID of the page that contains the block
* The page ID is in the URL when you open the page
* Use this page ID in the `pageId` parameter
2. **Want to insert after a specific block?**
* Use the page ID in the `pageId` parameter
* Pass the block ID in the `after` parameter
Example:
```json theme={null}
{
"pageId": "https://notion.so/My-Page-12345678123412341234123456789abc",
"after": "abcd1234-5678-90ef-abcd-ef1234567890",
"markdown": "# Your content"
}
```
3. **Identify the difference**:
```javascript theme={null}
// Page URL - use this ID for pageId parameter
https://notion.so/My-Page-abcd12345678901234567890abcdef123456
// Block URL (notice the #) - use page ID for pageId, block ID for "after"
https://notion.so/My-Page-abcd12345678901234567890abcdef123456#block123...
```
### Database ID Used Instead of Page ID
**Error Message**:
```
Provided ID aaaa1111-2222-3333-4444-bbbbccccdddd is a database, not a page.
Use the retrieve database API instead.
```
**What This Means**:
You're trying to add content directly to a database. You need to create or update pages within the database instead.
**Solutions**:
1. **Create a page in the database first**:
* You cannot append content directly to a database
* Create a new page in the database, then append to that page
* Or get the ID of an existing page in the database
2. **Get a page ID from the database**:
* Open a page within the database
* Copy that page's ID from the URL
* Use that page ID for your API request
### Archived Block Access
**Error Message**:
```
Can't edit block that is archived. You must unarchive the block before editing.
```
**What This Means**:
The page or block you're trying to modify has been archived in Notion.
**Solutions**:
1. **Unarchive the page/block**:
* Open the page in Notion
* Click "Restore"
2. **Check page status before editing**:
* Verify the page is not in the trash
* Ensure the parent page/database is not archived
## Notion API Limitations
**Good News:** The Mark2Notion API now automatically handles all Notion API content limitations. The errors listed below should no longer occur, as our system automatically splits or truncates content to meet Notion's requirements.
If you encounter any of these errors, please [contact support](mailto:hello@mark2notion.com).
### Rich Text Length Exceeded
**Error Message**:
```
body failed validation: body.children[0].paragraph.rich_text.length should be โค 100,
instead was 107
```
**Status**: **This issue is now automatically handled by the API**
**What This Means**:
Notion limits rich text arrays to 100 elements per block. Blocks exceeding this limit are automatically split into multiple blocks.
This issue has been fixed. If you're still seeing this error, please contact support at [hello@mark2notion.com](mailto:hello@mark2notion.com).
### Text Content Length Exceeded
**Error Message**:
```
body failed validation: body.children[0].paragraph.rich_text[0].text.content.length
should be โค 2000, instead was 8039
```
**What This Means**:
Individual text segments in Notion cannot exceed 2,000 characters.
**This issue was fixed.** The API now automatically handles text splitting.
If you're still seeing this error, it may indicate an issue with your Notion integration token. Please contact support.
## Request Validation Errors
### Missing Required Fields
**Error Messages**:
```json theme={null}
{"markdown": "Markdown is required"}
{"pageId": "Page ID is required"}
{"blocks": "Blocks must be a non-empty array"}
```
**What This Means**:
Your request is missing required parameters.
**Solutions**:
1. **Check required fields per endpoint**:
* [/api/convert](/api-reference/convert)
* [/api/append](/api-reference/append)
* [/api/append-blocks](/api-reference/append-blocks)
* [/api/clear-page](/api-reference/clear-page)
* [/api/notion-to-markdown](/api-reference/notion-to-markdown)
2. **Common mistakes**:
* โ Sending empty strings: `markdown: ""`
* โ Wrong data types: `pageId: 123` (should be string)
* โ Empty arrays: `blocks: []`
* โ Undefined/null values: `pageId: null`
### Empty or Invalid Markdown
**Error Messages**:
```json theme={null}
{"markdown": "Markdown cannot be empty"}
{"markdown": "No blocks generated from markdown"}
```
**What This Means**:
Your markdown content is empty or doesn't contain any valid content that can be converted to Notion blocks.
**Solutions**:
1. **Ensure non-empty content**:
* Markdown must contain actual text content, not just whitespace or newlines
* Check that your markdown string is not empty before sending
2. **Common invalid content**:
* โ Empty strings: `""`
* โ Only whitespace: `" "`
* โ Only newlines: `"\n\n\n"`
* โ
Valid: `"# Hello World"` or any text with letters/numbers
3. **Validate before sending**:
* Trim whitespace and check if the result has actual content
* Ensure the markdown contains at least some alphanumeric characters
### Invalid JSON in Request
**Error Messages**:
```
Invalid JSON
Failed to parse request JSON. Bad control character in string literal...
Expected double-quoted property name in JSON at position X
Unexpected token 'm', "markdown=%"... is not valid JSON
```
**What This Means**:
Your request body contains malformed JSON that cannot be parsed.
**Common Causes**:
* Unescaped special characters in strings (newlines, quotes, backslashes)
* Form-encoded data instead of JSON
* Syntax errors (missing commas, brackets, quotes)
* Incorrect Content-Type header
**Solutions**:
1. **Use proper JSON encoding**:
```javascript theme={null}
// โ
Good: Properly escaped
const body = JSON.stringify({
markdown: "Line 1\nLine 2\n\"Quoted\"",
pageId: "2c785200-4c6e-8182-ab77-dbbadb4daed6"
});
// โ Bad: Literal newlines and quotes
const body = '{
"markdown": "Line 1
Line 2
"Quoted"",
"pageId": "xxx"
}';
```
2. **Set correct Content-Type header**:
```javascript theme={null}
fetch('/api/append', {
method: 'POST',
headers: {
'Content-Type': 'application/json', // Important!
'x-api-key': 'your-api-key'
},
body: JSON.stringify({
markdown: content,
pageId: pageId
})
});
```
3. **Don't use form encoding**:
```javascript theme={null}
// โ Bad: Form-encoded
const body = 'markdown=' + encodeURIComponent(content);
// โ
Good: JSON
const body = JSON.stringify({ markdown: content });
```
4. **Escape special characters**:
```javascript theme={null}
// All special characters are automatically escaped by JSON.stringify
const markdown = `Content with "quotes", newlines\n, and \\ backslashes`;
const body = JSON.stringify({ markdown }); // Handles escaping
```
## Authentication Issues
### Invalid API Token
**Error Message**:
```
API token is invalid.
```
**What This Means**:
The Notion integration token is invalid or has been revoked.
**Solutions**:
1. **Check your Notion connection in the [dashboard](https://dashboard.mark2notion.com)** โ reconnect your workspace if needed
2. **If using a manual `notionToken`**:
* Go to [notion.so/my-integrations](https://notion.so/my-integrations)
* Verify the integration is active (not deleted)
* Regenerate a new secret if needed
* Tokens start with `ntn_` โ check for extra spaces when copying
### Missing API Key
For authentication issues with the Mark2Notion API key (not Notion token), see the [Error Handling](/errors#authentication-issues) page.
## Rate Limiting and Usage
### Quota Exceeded
**Error Message**:
```
Usage quota exceeded for current billing period
```
**What This Means**:
You've reached your monthly API request limit for your current plan.
**Solutions**:
1. **Check your usage**:
* Monitor your usage in the dashboard
2. **Wait for reset**:
* Free tier quotas reset monthly
* Check when your next billing period starts
3. **Upgrade your plan**:
* Visit the dashboard to upgrade to a higher tier
* Higher tiers offer more requests per month
See [Error Handling - Rate Limits](/errors#usage-limits) for more details.
### Usage Counter Not Found
**Error Message**:
```
No usage counter found for current period
```
**What This Means**:
This is an internal error related to usage tracking initialization.
**Solutions**:
1. **Retry the request**:
* This is usually a transient error
* Wait a few seconds and try again
2. **If it persists**:
* Contact support through the [feedback page](/feedback)
## Notion-Specific Errors
### Conflict on Save
**Error Message**:
```
Conflict occurred while saving. Please try again.
```
**What This Means**:
The page was modified by another user or process while your request was being processed.
**Solutions**:
1. **Retry the request**:
* This is usually a transient error
* Wait a few seconds and try again
* Use exponential backoff (wait longer between each retry)
2. **Avoid concurrent edits**:
* Don't make multiple simultaneous requests to the same page
* Implement request queuing for frequent updates
### Notion API Timeout
**Error Message**:
```
Request to Notion API has timed out
```
**What This Means**:
The request to Notion's API took too long and timed out.
**Common Causes**:
* Very large content being processed
* Notion API experiencing slowdowns
* Complex markdown with many blocks
**Solutions**:
1. **Retry the request**:
* Notion may be experiencing temporary issues
* Wait a few seconds before retrying
2. **Break up large requests**:
* If sending very large content, split it into smaller chunks
* Send chunks separately with small delays between requests
* This prevents timeouts and improves reliability
3. **Monitor Notion status**:
* Check [Notion's status page](https://status.notion.so/)
* If Notion is down, wait for recovery
## Still Having Issues?
If you're experiencing an error not covered here:
Report bugs or unexpected errors on GitHub
Get help from our support team
When reporting issues, include:
* The full error message
* The endpoint you're calling
* A minimal example that reproduces the issue
* Relevant request data (without sensitive tokens)
Check the [Error Handling](/errors) page for general error formats and best practices for handling API errors in your code.