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