Skip to main content
POST
/
api
/
clear-page
Clear Notion Page
curl --request POST \
  --url https://api.mark2notion.com/api/clear-page \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "notionToken": "<string>",
  "pageId": "<string>"
}
'
{
  "status": "<string>",
  "data": {
    "blocksDeleted": 123,
    "retryCount": 123
  }
}

​
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

​
x-api-key
string
required
Your Mark2Notion API key
​
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 clear. Pass the full notion.so page URL or just the page ID — both are accepted.

​
Response

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

​
Examples

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

​
Response Example

{
  "status": "success",
  "data": {
    "blocksDeleted": 42,
    "retryCount": 0
  }
}

​
Common Use Cases

​
Clear and Replace Page Content

Combine with the /append endpoint to replace page content: 
// 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: 
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 page for details.

​
Common Errors

StatusMeaning
400Missing or invalid pageId parameter
401Invalid Notion token or no access to the specified page
403Invalid API key
404Page does not exist or has been deleted
429Too 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)