Skip to main content
POST
https://api.mark2notion.com
/
api
/
append
Append to Notion Page
curl --request POST \
  --url https://api.mark2notion.com/api/append \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "markdown": "<string>",
  "notionToken": "<string>",
  "pageId": "<string>",
  "after": "<string>"
}
'
{
  "status": "success",
  "data": {
    "totalBlocks": 4,
    "requestCount": 1,
    "retryCount": 0,
    "lastBlockId": "f9e8d7c6-b5a4-3210-9876-543210fedcba"
  }
}

​
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: <span style="color: red">colored text</span>
  • 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 endpoint to append without reconverting.

​
Request

​
x-api-key
string
required
Your Mark2Notion API key
​
markdown
string
required
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.
​
notionToken
string
required
Your Notion integration token (from notion.so/my-integrations)
​
pageId
string
required
The ID of the Notion page to append content to
​
after
string
Optional block ID to append content after. If not provided, content is appended to the end of the page.

​
Response

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

​
Examples

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",
    "notionToken": "secret_NOTION_INTEGRATION_TOKEN",
    "pageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

{
  "status": "success",
  "data": {
    "totalBlocks": 4,
    "requestCount": 1,
    "retryCount": 0,
    "lastBlockId": "f9e8d7c6-b5a4-3210-9876-543210fedcba"
  }
}

​
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: 
{
  "markdown": "# New content",
  "notionToken": "secret_...",
  "pageId": "page-id",
  "after": "block-id-to-append-after"
}

​
Chaining Appends

Use the lastBlockId from the response to chain multiple append operations: 
// 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, you need:
  1. Create a Notion Integration
  2. Share Your Notion Page with the Integration
    • Open your target Notion page
    • Click the three dots (•••) in the top right corner
    • Select “Connections” → “Add connection”
    • Find and select your integration from the list
  3. Get the Page ID
    • From the page URL: notion.so/page-name-PAGE_ID
    • Or from the “Copy link” option

​
Error Responses

Handle Errors

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

Deep Nesting Preservation

Handles unlimited nesting depth (5, 6, 7+ levels) by breaking into sub-requests while maintaining parent-child relationships

Large Document Support

Automatically splits documents with 1000+ blocks into manageable chunks without losing content order

Content Truncation Warnings

Provides clear warnings when URLs or equations are truncated, so you know exactly what was modified

Transparent Pricing

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.