> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mark2notion.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> 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

<CardGroup cols={2}>
  <Card title="Convert" icon="code" href="/api-reference/convert">
    Convert Markdown text to Notion block JSON without touching Notion
  </Card>

  <Card title="Append" icon="plus" href="/api-reference/append">
    Convert Markdown and append it directly to a Notion page
  </Card>

  <Card title="Append Blocks" icon="layer-group" href="/api-reference/append-blocks">
    Append pre-converted Notion blocks to a page
  </Card>

  <Card title="Clear Page" icon="eraser" href="/api-reference/clear-page">
    Archive all content blocks from a Notion page
  </Card>
</CardGroup>

### Content Extraction

<Card title="Notion to Markdown" icon="download" href="/api-reference/notion-to-markdown">
  Extract content from a Notion page and convert it to Markdown
</Card>

## 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