my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	---
#2	name: notion
#3	description: Notion API for creating and managing pages, databases, and blocks.
#4	homepage: https://developers.notion.com
#5	metadata: {"clawdbot":{"emoji":"📝"}}
#6	---
#7
#8	# notion
#9
#10	Use the Notion API to create/read/update pages, data sources (databases), and blocks.
#11
#12	## Setup
#13
#14	1. Create an integration at https://notion.so/my-integrations
#15	2. Copy the API key (starts with `ntn_` or `secret_`)
#16	3. Store it:
#17	```bash
#18	mkdir -p ~/.config/notion
#19	echo "ntn_your_key_here" > ~/.config/notion/api_key
#20	```
#21	4. Share target pages/databases with your integration (click "..." → "Connect to" → your integration name)
#22
#23	## API Basics
#24
#25	All requests need:
#26	```bash
#27	NOTION_KEY=$(cat ~/.config/notion/api_key)
#28	curl -X GET "https://api.notion.com/v1/..." \
#29	-H "Authorization: Bearer $NOTION_KEY" \
#30	-H "Notion-Version: 2025-09-03" \
#31	-H "Content-Type: application/json"
#32	```
#33
#34	> Note: The `Notion-Version` header is required. This skill uses `2025-09-03` (latest). In this version, databases are called "data sources" in the API.
#35
#36	## Common Operations
#37
#38	Search for pages and data sources:
#39	```bash
#40	curl -X POST "https://api.notion.com/v1/search" \
#41	-H "Authorization: Bearer $NOTION_KEY" \
#42	-H "Notion-Version: 2025-09-03" \
#43	-H "Content-Type: application/json" \
#44	-d '{"query": "page title"}'
#45	```
#46
#47	Get page:
#48	```bash
#49	curl "https://api.notion.com/v1/pages/{page_id}" \
#50	-H "Authorization: Bearer $NOTION_KEY" \
#51	-H "Notion-Version: 2025-09-03"
#52	```
#53
#54	Get page content (blocks):
#55	```bash
#56	curl "https://api.notion.com/v1/blocks/{page_id}/children" \
#57	-H "Authorization: Bearer $NOTION_KEY" \
#58	-H "Notion-Version: 2025-09-03"
#59	```
#60
#61	Create page in a data source:
#62	```bash
#63	curl -X POST "https://api.notion.com/v1/pages" \
#64	-H "Authorization: Bearer $NOTION_KEY" \
#65	-H "Notion-Version: 2025-09-03" \
#66	-H "Content-Type: application/json" \
#67	-d '{
#68	"parent": {"database_id": "xxx"},
#69	"properties": {
#70	"Name": {"title": [{"text": {"content": "New Item"}}]},
#71	"Status": {"select": {"name": "Todo"}}
#72	}
#73	}'
#74	```
#75
#76	Query a data source (database):
#77	```bash
#78	curl -X POST "https://api.notion.com/v1/data_sources/{data_source_id}/query" \
#79	-H "Authorization: Bearer $NOTION_KEY" \
#80	-H "Notion-Version: 2025-09-03" \
#81	-H "Content-Type: application/json" \
#82	-d '{
#83	"filter": {"property": "Status", "select": {"equals": "Active"}},
#84	"sorts": [{"property": "Date", "direction": "descending"}]
#85	}'
#86	```
#87
#88	Create a data source (database):
#89	```bash
#90	curl -X POST "https://api.notion.com/v1/data_sources" \
#91	-H "Authorization: Bearer $NOTION_KEY" \
#92	-H "Notion-Version: 2025-09-03" \
#93	-H "Content-Type: application/json" \
#94	-d '{
#95	"parent": {"page_id": "xxx"},
#96	"title": [{"text": {"content": "My Database"}}],
#97	"properties": {
#98	"Name": {"title": {}},
#99	"Status": {"select": {"options": [{"name": "Todo"}, {"name": "Done"}]}},
#100	"Date": {"date": {}}
#101	}
#102	}'
#103	```
#104
#105	Update page properties:
#106	```bash
#107	curl -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
#108	-H "Authorization: Bearer $NOTION_KEY" \
#109	-H "Notion-Version: 2025-09-03" \
#110	-H "Content-Type: application/json" \
#111	-d '{"properties": {"Status": {"select": {"name": "Done"}}}}'
#112	```
#113
#114	Add blocks to page:
#115	```bash
#116	curl -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" \
#117	-H "Authorization: Bearer $NOTION_KEY" \
#118	-H "Notion-Version: 2025-09-03" \
#119	-H "Content-Type: application/json" \
#120	-d '{
#121	"children": [
#122	{"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Hello"}}]}}
#123	]
#124	}'
#125	```
#126
#127	## Property Types
#128
#129	Common property formats for database items:
#130	- Title: `{"title": [{"text": {"content": "..."}}]}`
#131	- Rich text: `{"rich_text": [{"text": {"content": "..."}}]}`
#132	- Select: `{"select": {"name": "Option"}}`
#133	- Multi-select: `{"multi_select": [{"name": "A"}, {"name": "B"}]}`
#134	- Date: `{"date": {"start": "2024-01-15", "end": "2024-01-16"}}`
#135	- Checkbox: `{"checkbox": true}`
#136	- Number: `{"number": 42}`
#137	- URL: `{"url": "https://..."}`
#138	- Email: `{"email": "a@b.com"}`
#139	- Relation: `{"relation": [{"id": "page_id"}]}`
#140
#141	## Key Differences in 2025-09-03
#142
#143	- Databases → Data Sources: Use `/data_sources/` endpoints for queries and retrieval
#144	- Two IDs: Each database now has both a `database_id` and a `data_source_id`
#145	- Use `database_id` when creating pages (`parent: {"database_id": "..."}`)
#146	- Use `data_source_id` when querying (`POST /v1/data_sources/{id}/query`)
#147	- Search results: Databases return as `"object": "data_source"` with their `data_source_id`
#148	- Parent in responses: Pages show `parent.data_source_id` alongside `parent.database_id`
#149	- Finding the data_source_id: Search for the database, or call `GET /v1/data_sources/{data_source_id}`
#150
#151	## Notes
#152
#153	- Page/database IDs are UUIDs (with or without dashes)
#154	- The API cannot set database view filters — that's UI-only
#155	- Rate limit: ~3 requests/second average
#156	- Use `is_inline: true` when creating data sources to embed them in pages
#157

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public