Documentation

API Documentation

Everything you need to integrate Notion Embed into your applications. RESTful API with comprehensive documentation.

Quick Start GuideGet API Key
Authentication
Endpoints
Rate Limits
Webhooks
Security
Examples

Quick Start

Get started with the Notion Embed API in minutes. Follow these steps to create your first embed programmatically.

cURL
curl -X POST https://api.notionembed.com/v1/embeds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notion_page_id": "your-notion-page-id",
    "options": {
      "remove_branding": true,
      "custom_css": ".notion-page { font-family: Inter; }"
    }
  }'

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Security Note: Never expose your API key in client-side code. Always make API calls from your server.

Base URL

All API requests should be made to:

https://api.notionembed.com/v1

Endpoints

POST/embeds

Create a new embed for a Notion page.

Request Body

{
  "notion_page_id": "string (required)",
  "options": {
    "remove_branding": "boolean",
    "custom_css": "string",
    "custom_domain": "string"
  }
}
GET/embeds/:id

Retrieve details about a specific embed.

GET/embeds

List all embeds in your account.

DELETE/embeds/:id

Delete an embed.

Rate Limits

API rate limits vary by plan:

PlanRequests/minRequests/day
Pro6010,000
Enterprise300100,000

Webhooks

Receive real-time notifications when events occur in your Notion Embed account.

Available Events

  • embed.created - New embed created
  • embed.updated - Embed settings changed
  • embed.deleted - Embed removed
  • page.synced - Notion page content synced

Security Best Practices

  • Never expose API keys in client-side code

    Always make API calls from your server.

  • Use environment variables

    Store API keys in environment variables, not in code.

  • Rotate keys regularly

    Regenerate your API keys periodically for enhanced security.

  • Verify webhook signatures

    Always validate webhook payloads using the provided signature.

Code Examples

JavaScript / Node.js

JavaScript
const response = await fetch('https://api.notionembed.com/v1/embeds', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    notion_page_id: 'your-notion-page-id',
    options: {
      remove_branding: true,
    },
  }),
});

const embed = await response.json();
console.log(embed.embed_url);

Python

Python
import requests

response = requests.post(
    'https://api.notionembed.com/v1/embeds',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'notion_page_id': 'your-notion-page-id',
        'options': {
            'remove_branding': True,
        },
    },
)

embed = response.json()
print(embed['embed_url'])