notion-api-skillNotion API integration with managed OAuth. Query databases, create and update pages, manage blocks. Use this skill when users want to interact with Notion workspaces, databases, or pages. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
Install via ClawdBot CLI:
clawdbot install byungkyu/notion-api-skillAccess the Notion API with managed OAuth authentication. Query databases, create pages, manage blocks, and search your workspace.
# Search for pages
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'query': 'meeting notes'}).encode()
req = urllib.request.Request('https://gateway.maton.ai/notion/v1/search', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
req.add_header('Notion-Version', '2025-09-03')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFhttps://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.
All Notion API requests require the version header:
Notion-Version: 2025-09-03All requests require the Maton API key in the Authorization header:
Authorization: Bearer $MATON_API_KEYEnvironment Variable: Set your API key as MATON_API_KEY:
export MATON_API_KEY="YOUR_API_KEY"Manage your Notion OAuth connections at https://ctrl.maton.ai.
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=notion&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFpython <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'notion'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFpython <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFResponse:
{
"connection": {
"connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
"status": "ACTIVE",
"creation_time": "2025-12-08T07:20:53.488460Z",
"last_updated_time": "2026-01-31T20:03:32.593153Z",
"url": "https://connect.maton.ai/?session_token=...",
"app": "notion",
"metadata": {}
}
}Open the returned url in a browser to complete OAuth authorization.
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFIf you have multiple Notion connections, specify which one to use with the Maton-Connection header:
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'query': 'meeting notes'}).encode()
req = urllib.request.Request('https://gateway.maton.ai/notion/v1/search', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
req.add_header('Notion-Version', '2025-09-03')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFIf omitted, the gateway uses the default (oldest) active connection.
In API version 2025-09-03, databases and data sources are separate:
| Concept | Use For |
|---------|---------|
| Database | Creating databases, getting data source IDs |
| Data Source | Querying, updating schema, updating properties |
Use GET /databases/{id} to get the data_sources array, then use /data_sources/ endpoints:
{
"object": "database",
"id": "abc123",
"data_sources": [
{"id": "def456", "name": "My Database"}
]
}Search for pages:
POST /notion/v1/search
Content-Type: application/json
Notion-Version: 2025-09-03
{
"query": "meeting notes",
"filter": {"property": "object", "value": "page"}
}Search for data sources:
POST /notion/v1/search
Content-Type: application/json
Notion-Version: 2025-09-03
{
"filter": {"property": "object", "value": "data_source"}
}GET /notion/v1/data_sources/{dataSourceId}
Notion-Version: 2025-09-03POST /notion/v1/data_sources/{dataSourceId}/query
Content-Type: application/json
Notion-Version: 2025-09-03
{
"filter": {
"property": "Status",
"select": {"equals": "Active"}
},
"sorts": [
{"property": "Created", "direction": "descending"}
],
"page_size": 100
}PATCH /notion/v1/data_sources/{dataSourceId}
Content-Type: application/json
Notion-Version: 2025-09-03
{
"title": [{"type": "text", "text": {"content": "Updated Title"}}],
"properties": {
"NewColumn": {"rich_text": {}}
}
}GET /notion/v1/databases/{databaseId}
Notion-Version: 2025-09-03POST /notion/v1/databases
Content-Type: application/json
Notion-Version: 2025-09-03
{
"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"}]}}
}
}GET /notion/v1/pages/{pageId}
Notion-Version: 2025-09-03POST /notion/v1/pages
Content-Type: application/json
Notion-Version: 2025-09-03
{
"parent": {"page_id": "PARENT_PAGE_ID"},
"properties": {
"title": {"title": [{"text": {"content": "New Page"}}]}
}
}POST /notion/v1/pages
Content-Type: application/json
Notion-Version: 2025-09-03
{
"parent": {"data_source_id": "DATA_SOURCE_ID"},
"properties": {
"Name": {"title": [{"text": {"content": "New Page"}}]},
"Status": {"select": {"name": "Active"}}
}
}PATCH /notion/v1/pages/{pageId}
Content-Type: application/json
Notion-Version: 2025-09-03
{
"properties": {
"Status": {"select": {"name": "Done"}}
}
}PATCH /notion/v1/pages/{pageId}
Content-Type: application/json
Notion-Version: 2025-09-03
{
"icon": {"type": "emoji", "emoji": "🚀"}
}PATCH /notion/v1/pages/{pageId}
Content-Type: application/json
Notion-Version: 2025-09-03
{
"archived": true
}GET /notion/v1/blocks/{blockId}/children
Notion-Version: 2025-09-03PATCH /notion/v1/blocks/{blockId}/children
Content-Type: application/json
Notion-Version: 2025-09-03
{
"children": [
{
"object": "block",
"type": "paragraph",
"paragraph": {
"rich_text": [{"type": "text", "text": {"content": "New paragraph"}}]
}
}
]
}DELETE /notion/v1/blocks/{blockId}
Notion-Version: 2025-09-03GET /notion/v1/users
Notion-Version: 2025-09-03GET /notion/v1/users/me
Notion-Version: 2025-09-03equals, does_not_equalcontains, does_not_containstarts_with, ends_withis_empty, is_not_emptygreater_than, less_thanparagraph, heading_1, heading_2, heading_3bulleted_list_item, numbered_list_itemto_do, code, quote, dividerconst response = await fetch('https://gateway.maton.ai/notion/v1/search', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
'Notion-Version': '2025-09-03'
},
body: JSON.stringify({ query: 'meeting' })
});import os
import requests
response = requests.post(
'https://gateway.maton.ai/notion/v1/search',
headers={
'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
'Notion-Version': '2025-09-03'
},
json={'query': 'meeting'}
)GET /databases/{id} to get the data_sources array containing data source IDsPOST /databases endpointarchived: truecurl -g when URLs contain brackets (fields[], sort[], records[]) to disable glob parsingjq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments. You may get "Invalid API key" errors when piping.| Status | Meaning |
|--------|---------|
| 400 | Missing Notion connection |
| 401 | Invalid or missing Maton API key |
| 429 | Rate limited (10 req/sec per account) |
| 4xx/5xx | Passthrough error from Notion API |
MATON_API_KEY environment variable is set:echo $MATON_API_KEYpython <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFnotion. For example:https://gateway.maton.ai/notion/v1/searchhttps://gateway.maton.ai/v1/searchGenerated Mar 1, 2026
A marketing agency uses this skill to query Notion databases for client project statuses, automatically updating dashboards with real-time data on tasks, deadlines, and budgets. This enables managers to track progress without manual entry, improving oversight and client reporting efficiency.
A tech startup integrates the skill to search and create pages in Notion for meeting notes, syncing action items and decisions directly from collaboration tools. This reduces administrative overhead and ensures all team members have access to updated records, enhancing meeting follow-through.
A media company employs the skill to manage Notion data sources for editorial calendars, querying upcoming content schedules and updating publication dates based on analytics. This streamlines content planning and coordination across writers and editors, boosting editorial output.
An e-commerce business uses the skill to query Notion databases for support tickets, updating statuses and assigning agents based on priority filters. This automates ticket routing and provides real-time insights into resolution times, improving customer service responsiveness.
A consulting firm leverages the skill to search and update Notion pages for market research data, consolidating findings from various sources into structured databases. This facilitates data analysis and report generation, supporting informed decision-making for clients.
A company builds a platform that integrates Notion with other productivity tools using this skill, offering subscription-based access to automated workflows and data sync features. Revenue is generated through tiered pricing plans based on usage and advanced functionalities.
A digital agency provides Notion automation services to clients, using the skill to set up and manage custom databases and pages for project tracking and reporting. Revenue comes from one-time setup fees and ongoing maintenance contracts, tailored to client needs.
A software developer creates an enterprise tool that embeds Notion capabilities via this skill, enabling large organizations to streamline internal processes like HR onboarding or inventory management. Revenue is sourced from enterprise licensing deals and custom development projects.
💬 Integration Tip
Ensure the MATON_API_KEY is securely stored and use the Maton-Connection header to manage multiple Notion workspaces, avoiding conflicts in multi-tenant environments.
Use the mcporter CLI to list, configure, auth, and call MCP servers/tools directly (HTTP or stdio), including ad-hoc servers, config edits, and CLI/type generation.
Connect to 100+ APIs (Google Workspace, Microsoft 365, GitHub, Notion, Slack, Airtable, HubSpot, etc.) with managed OAuth. Use this skill when users want to...
Build, debug, and deploy websites using HTML, CSS, JavaScript, and modern frameworks following production best practices.
YouTube Data API integration with managed OAuth. Search videos, manage playlists, access channel data, and interact with comments. Use this skill when users want to interact with YouTube. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
Scaffold, test, document, and debug REST and GraphQL APIs. Use when the user needs to create API endpoints, write integration tests, generate OpenAPI specs, test with curl, mock APIs, or troubleshoot HTTP issues.
Search for jobs across LinkedIn, Indeed, Glassdoor, ZipRecruiter, Google Jobs, Bayt, Naukri, and BDJobs using the JobSpy MCP server.