POST
/
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.

​
Request

​
x-api-key
string
required
Your Mark2Notion API key
​
markdown
string
required
The Markdown content to convert and append
​
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 Page
    • Open your Notion page
    • Click “Share” → “Invite”
    • Add your integration
  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

​
📊 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.