Append Prebuilt Blocks

Append already-converted Notion blocks directly to a page

POST /api/append-blocks

Append Prebuilt Blocks

cURL

curl --request POST \
  --url https://api.mark2notion.com/api/append-blocks \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "blocks": [
    {}
  ],
  "notionToken": "<string>",
  "pageId": "<string>",
  "after": "<string>"
}
'

Standard Response

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

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

x-api-key · string · required

Your Mark2Notion API key

blocks · array · required

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.

notionToken · string

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.

pageId · string · required

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.

after · string

Optional block ID to append content after. If omitted, blocks are appended to the end of the page.

Response

status · string

Will be “success” for successful requests

data · object

Show data

totalBlocks · number

Total number of blocks that were appended

requestCount · number

Number of internal Notion API requests made (for transparency - does NOT affect your usage quota)

retryCount · number

Number of retry attempts caused by rate limiting

lastBlockId · string

ID of the last block that was created (use this for subsequent after appends)

Examples

curl

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"
  }'

Standard Response

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

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 endpoint first and then pass the resulting array here.