Notion

Notion

Access the Notion API with managed OAuth authentication. Query databases, create pages, manage blocks, and search your workspace.

Quick Start Search for pages curl -X POST https://gateway.maton.ai/notion/v1/search \ -H "Authorization: Bearer $MATON_API_KEY" \ -H "Content-Type: application/json" \ -H "Notion-Version: 2025-09-03" \ -d '{ "query": "meeting notes" }'

Base URL https://gateway.maton.ai/notion/{native-api-path}

Replace {native-api-path} with the actual Notion API endpoint path. The gateway proxies requests to api.notion.com and automatically injects your OAuth token.

Required Headers

All Notion API requests require:

Notion-Version: 2025-09-03 Authorization: Bearer $MATON_API_KEY Content-Type: application/json

Authentication

Set your API key:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key Sign in or create an account at maton.ai Go to maton.ai/settings Copy your API key Connection Management

Manage your Notion OAuth connections at:

https://ctrl.maton.ai

List Connections curl "https://ctrl.maton.ai/connections?app=notion&status=ACTIVE" \ -H "Authorization: Bearer $MATON_API_KEY"

Create Connection curl -X POST https://ctrl.maton.ai/connections \ -H "Authorization: Bearer $MATON_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "app": "notion" }'

Get Connection curl https://ctrl.maton.ai/connections/{connection_id} \ -H "Authorization: Bearer $MATON_API_KEY"

Delete Connection curl -X DELETE https://ctrl.maton.ai/connections/{connection_id} \ -H "Authorization: Bearer $MATON_API_KEY"

Complete OAuth

Open the returned url from the connection response in a browser.

Specifying Connection curl -X POST https://gateway.maton.ai/notion/v1/search \ -H "Authorization: Bearer $MATON_API_KEY" \ -H "Content-Type: application/json" \ -H "Notion-Version: 2025-09-03" \ -H "Maton-Connection: 21fd90f9-5935-43cd-b6c8-bde9d915ca80" \ -d '{ "query": "meeting notes" }'

Key Concept: Databases vs Data Sources Concept Use For Database Creating databases, getting data source IDs Data Source Querying, updating schema, properties

Example response:

{ "object": "database", "id": "abc123", "data_sources": [ {"id": "def456", "name": "My Database"} ] }

API Reference Search Search for pages curl -X POST https://gateway.maton.ai/notion/v1/search \ -H "Authorization: Bearer $MATON_API_KEY" \ -H "Content-Type: application/json" \ -H "Notion-Version: 2025-09-03" \ -d '{ "query": "meeting notes", "filter": { "property": "object", "value": "page" } }'

Search for data sources curl -X POST https://gateway.maton.ai/notion/v1/search \ -H "Authorization: Bearer $MATON_API_KEY" \ -H "Content-Type: application/json" \ -H "Notion-Version: 2025-09-03" \ -d '{ "filter": { "property": "object", "value": "data_source" } }'

Data Sources Get Data Source curl https://gateway.maton.ai/notion/v1/data_sources/{dataSourceId} \ -H "Authorization: Bearer $MATON_API_KEY" \ -H "Notion-Version: 2025-09-03"

Query Data Source curl -X POST https://gateway.maton.ai/notion/v1/data_sources/{dataSourceId}/query \ -H "Authorization: Bearer $MATON_API_KEY" \ -H "Content-Type: application/json" \ -H "Notion-Version: 2025-09-03" \ -d '{ "filter": { "property": "Status", "select": { "equals": "Active" } }, "sorts": [ { "property": "Created", "direction": "descending" } ], "page_size": 100 }'

Update Data Source curl -X PATCH https://gateway.maton.ai/notion/v1/data_sources/{dataSourceId} \ -H "Authorization: Bearer $MATON_API_KEY" \ -H "Content-Type: application/json" \ -H "Notion-Version: 2025-09-03" \ -d '{ "title": [{ "type": "text", "text": { "content": "Updated Title" } }], "properties": { "NewColumn": { "rich_text": {} } } }'

Databases Get Database curl https://gateway.maton.ai/notion/v1/databases/{databaseId} \ -H "Authorization: Bearer $MATON_API_KEY" \ -H "Notion-Version: 2025-09-03"

Create Database curl -X POST https://gateway.maton.ai/notion/v1/databases \ -H "Authorization: Bearer $MATON_API_KEY" \ -H "Content-Type: application/json" \ -H "Notion-Version: 2025-09-03" \ -d '{ "parent": { "type": "page_id", "page_id": "PARENT_PAGE_ID" }, "title": [{ "type": "text", "text": { "content": "New Database" } }], "properties": { "Name": { "title": {} }, "Status": { "select": { "options": [{ "name": "Active" }, { "name": "Done" }] } } } }'

Pages Get Page curl https://gateway.maton.ai/notion/v1/pages/{pageId} \ -H "Authorization: Bearer $MATON_API_KEY" \ -H "Notion-Version: 2025-09-03"

Create Page curl -X POST https://gateway.maton.ai/notion/v1/pages \ -H "Authorization: Bearer $MATON_API_KEY" \ -H "Content-Type: application/json" \ -H "Notion-Version: 2025-09-03" \ -d '{ "parent": { "page_id": "PARENT_PAGE_ID" }, "properties": { "title": { "title": [{ "text": { "content": "New Page" } }] } } }'

Create Page in Data Source curl -X POST https://gateway.maton.ai/notion/v1/pages \ -H "Authorization: Bearer $MATON_API_KEY" \ -H "Content-Type: application/json" \ -H "Notion-Version: 2025-09-03" \ -d '{ "parent": { "data_source_id": "DATA_SOURCE_ID" }, "properties": { "Name": { "title": [{ "text": { "content": "New Page" } }] }, "Status": { "select": { "name": "Active" } } } }'

Update Page Properties curl -X PATCH https://gateway.maton.ai/notion/v1/pages/{pageId} \ -H "Authorization: Bearer $MATON_API_KEY" \ -H "Content-Type: application/json" \ -H "Notion-Version: 2025-09-03" \ -d '{ "properties": { "Status": { "select": { "name": "Done" } } } }'

Archive Page curl -X PATCH https://gateway.maton.ai/notion/v1/pages/{pageId} \ -H "Authorization: Bearer $MATON_API_KEY" \ -H "Content-Type: application/json" \ -H "Notion-Version: 2025-09-03" \ -d '{ "archived": true }'

Blocks Get Block Children curl https://gateway.maton.ai/notion/v1/blocks/{blockId}/children \ -H "Authorization: Bearer $MATON_API_KEY" \ -H "Notion-Version: 2025-09-03"

Append Block Children curl -X PATCH https://gateway.maton.ai/notion/v1/blocks/{blockId}/children \ -H "Authorization: Bearer $MATON_API_KEY" \ -H "Content-Type: application/json" \ -H "Notion-Version: 2025-09-03" \ -d '{ "children": [ { "object": "block", "type": "paragraph", "paragraph": { "rich_text": [ { "type": "text", "text": { "content": "New paragraph" } } ] } } ] }'

Delete Block curl -X DELETE https://gateway.maton.ai/notion/v1/blocks/{blockId} \ -H "Authorization: Bearer $MATON_API_KEY" \ -H "Notion-Version: 2025-09-03"

Users List Users curl https://gateway.maton.ai/notion/v1/users \ -H "Authorization: Bearer $MATON_API_KEY" \ -H "Notion-Version: 2025-09-03"

Get Current User curl https://gateway.maton.ai/notion/v1/users/me \ -H "Authorization: Bearer $MATON_API_KEY" \ -H "Notion-Version: 2025-09-03"

Notes All IDs are UUIDs Use /databases/{id} to retrieve data_sources Use curl -g if your URL contains brackets ([]) Avoid piping issues with $MATON_API_KEY in some shells Error Handling Status Meaning 400 Missing Notion connection 401 Invalid API key 429 Rate limited 4xx/5xx Notion API error Troubleshooting Check API key echo $MATON_API_KEY

Test connection curl https://ctrl.maton.ai/connections \ -H "Authorization: Bearer $MATON_API_KEY"

Common Mistake

Correct:

https://gateway.maton.ai/notion/v1/search

Incorrect:

https://gateway.maton.ai/v1/search