Notion

Overview

The Notion API lets you read and write Notion pages, databases, and blocks programmatically — build automations, sync content, and create tools on top of Notion’s workspace. Auth is OAuth (integration token) — there’s no anonymous access.

Quick Start

An integration token (secret_... from a Notion integration) is required:

# List the pages/databases the integration can access:
curl "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer YOUR_INTEGRATION_TOKEN" \
  -H "Notion-Version: 2022-06-28"

Query a database:

curl -X POST "https://api.notion.com/v1/databases/DATABASE_ID/query" \
  -H "Authorization: Bearer YOUR_INTEGRATION_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{"page_size": 10}'

Create a page:

curl -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer YOUR_INTEGRATION_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{"parent": {"database_id": "DATABASE_ID"}, "properties": {"Name": {"title": [{"text": {"content": "New task"}}]}}}'

Authentication

• Create an integration at notion.so/my-integrations → copy the Internal Integration Token (secret_...).
• Send it as Authorization: Bearer ... with the Notion-Version header (always required, e.g. 2022-06-28).
• OAuth (public integrations) is the same API with user-authorized tokens — the listing’s OAuth flag covers this.

Rate Limits & Notes

• Rate limit: ~3 requests/second per integration — cache responses.
• Always send the Notion-Version header — the API is versioned.
• The integration only sees pages/databases it’s been shared with (share the page with the integration in the UI).
• Database queries are POST to /v1/databases/{id}/query (JSON body), not GET.

FAQ

Is Notion API free? Yes — the API is free for integrations (within rate limits).

Do I need OAuth? Internal integrations use a token; public integrations use OAuth — same API.

Why can’t my integration see pages? You must share each page/database with the integration in the Notion UI.