Notion Embed API: Developer Guide for Custom Integrations

API Overview

Notion's Official API

Notion provides a REST API for:

Limitations for Embedding

The official API doesn't render pages. For embedding:

Authentication

Creating an Integration

API Token

Authorization: Bearer {your-notion-api-token}

Share with Integration

Each page must be shared with your integration to access it.

Key Endpoints

Retrieve a Page

GET https://api.notion.com/v1/pages/{page_id}

Query a Database

POST https://api.notion.com/v1/databases/{database_id}/query

Get Page Content

GET https://api.notion.com/v1/blocks/{block_id}/children

Code Examples

Node.js

const { Client } = require('@notionhq/client');
const notion = new Client({ auth: process.env.NOTION_API_KEY });
async function getPage(pageId) {
  const response = await notion.pages.retrieve({ page_id: pageId });
  return response;
}
async function getPageContent(pageId) {
  const response = await notion.blocks.children.list({ block_id: pageId });
  return response.results;
}

Python

import requests
headers = {
    "Authorization": f"Bearer {NOTION_API_KEY}",
    "Notion-Version": "2022-06-28"
}
def get_page(page_id):
    url = f"https://api.notion.com/v1/pages/{page_id}"
    response = requests.get(url, headers=headers)
    return response.json()

Building Custom Embeds

The Challenge

Official API returns JSON, not rendered HTML. You must:

Easier Option: Notion Embed API

Notion Embed API provides:

Notion Embed API Example

// Generate embed URL
const embedUrl = https://notionembed.com/embed/{your-embed-id};
// Use in your application
<iframe src={embedUrl} />

Notion Embed API Features

Notion Embed Enterprise ($27.90/mo) includes:

Example API Call

// Create embed programmatically
const response = await fetch('https://api.notionembed.com/v1/embeds', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {api-key}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    notionUrl: 'https://notion.site/Page-abc123',
    settings: {
      removeBranding: true,
      customDomain: 'docs.yoursite.com'
    }
  })
});

FAQ

Can I render Notion pages from the API?

The official API returns structured data, not HTML. You'd need to build a renderer or use Notion Embed.

Is there an official embed API?

No, Notion doesn't provide an embed API. Notion Embed fills this gap.

What are API rate limits?

Notion: 3 requests/second per integration. Check current limits in their docs.

Conclusion

Notion API is powerful but requires work for embedding:

Access Notion Embed API →

---

Related: GitHub Embed | Developer Documentation