{"skill":{"slug":"notion","displayName":"Notion","summary":"Notion API for creating and managing pages, databases, and blocks.","description":"---\nname: notion\ndescription: Notion API for creating and managing pages, databases, and blocks.\nhomepage: https://developers.notion.com\nmetadata: {\"clawdbot\":{\"emoji\":\"📝\"}}\n---\n\n# notion\n\nUse the Notion API to create/read/update pages, data sources (databases), and blocks.\n\n## Setup\n\n1. Create an integration at https://notion.so/my-integrations\n2. Copy the API key (starts with `ntn_` or `secret_`)\n3. Store it:\n```bash\nmkdir -p ~/.config/notion\necho \"ntn_your_key_here\" > ~/.config/notion/api_key\n```\n4. Share target pages/databases with your integration (click \"...\" → \"Connect to\" → your integration name)\n\n## API Basics\n\nAll requests need:\n```bash\nNOTION_KEY=$(cat ~/.config/notion/api_key)\ncurl -X GET \"https://api.notion.com/v1/...\" \\\n  -H \"Authorization: Bearer $NOTION_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application/json\"\n```\n\n> **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.\n\n## Common Operations\n\n**Search for pages and data sources:**\n```bash\ncurl -X POST \"https://api.notion.com/v1/search\" \\\n  -H \"Authorization: Bearer $NOTION_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"page title\"}'\n```\n\n**Get page:**\n```bash\ncurl \"https://api.notion.com/v1/pages/{page_id}\" \\\n  -H \"Authorization: Bearer $NOTION_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\"\n```\n\n**Get page content (blocks):**\n```bash\ncurl \"https://api.notion.com/v1/blocks/{page_id}/children\" \\\n  -H \"Authorization: Bearer $NOTION_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\"\n```\n\n**Create page in a data source:**\n```bash\ncurl -X POST \"https://api.notion.com/v1/pages\" \\\n  -H \"Authorization: Bearer $NOTION_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"parent\": {\"database_id\": \"xxx\"},\n    \"properties\": {\n      \"Name\": {\"title\": [{\"text\": {\"content\": \"New Item\"}}]},\n      \"Status\": {\"select\": {\"name\": \"Todo\"}}\n    }\n  }'\n```\n\n**Query a data source (database):**\n```bash\ncurl -X POST \"https://api.notion.com/v1/data_sources/{data_source_id}/query\" \\\n  -H \"Authorization: Bearer $NOTION_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"filter\": {\"property\": \"Status\", \"select\": {\"equals\": \"Active\"}},\n    \"sorts\": [{\"property\": \"Date\", \"direction\": \"descending\"}]\n  }'\n```\n\n**Create a data source (database):**\n```bash\ncurl -X POST \"https://api.notion.com/v1/data_sources\" \\\n  -H \"Authorization: Bearer $NOTION_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"parent\": {\"page_id\": \"xxx\"},\n    \"title\": [{\"text\": {\"content\": \"My Database\"}}],\n    \"properties\": {\n      \"Name\": {\"title\": {}},\n      \"Status\": {\"select\": {\"options\": [{\"name\": \"Todo\"}, {\"name\": \"Done\"}]}},\n      \"Date\": {\"date\": {}}\n    }\n  }'\n```\n\n**Update page properties:**\n```bash\ncurl -X PATCH \"https://api.notion.com/v1/pages/{page_id}\" \\\n  -H \"Authorization: Bearer $NOTION_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"properties\": {\"Status\": {\"select\": {\"name\": \"Done\"}}}}'\n```\n\n**Add blocks to page:**\n```bash\ncurl -X PATCH \"https://api.notion.com/v1/blocks/{page_id}/children\" \\\n  -H \"Authorization: Bearer $NOTION_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"children\": [\n      {\"object\": \"block\", \"type\": \"paragraph\", \"paragraph\": {\"rich_text\": [{\"text\": {\"content\": \"Hello\"}}]}}\n    ]\n  }'\n```\n\n## Property Types\n\nCommon property formats for database items:\n- **Title:** `{\"title\": [{\"text\": {\"content\": \"...\"}}]}`\n- **Rich text:** `{\"rich_text\": [{\"text\": {\"content\": \"...\"}}]}`\n- **Select:** `{\"select\": {\"name\": \"Option\"}}`\n- **Multi-select:** `{\"multi_select\": [{\"name\": \"A\"}, {\"name\": \"B\"}]}`\n- **Date:** `{\"date\": {\"start\": \"2024-01-15\", \"end\": \"2024-01-16\"}}`\n- **Checkbox:** `{\"checkbox\": true}`\n- **Number:** `{\"number\": 42}`\n- **URL:** `{\"url\": \"https://...\"}`\n- **Email:** `{\"email\": \"a@b.com\"}`\n- **Relation:** `{\"relation\": [{\"id\": \"page_id\"}]}`\n\n## Key Differences in 2025-09-03\n\n- **Databases → Data Sources:** Use `/data_sources/` endpoints for queries and retrieval\n- **Two IDs:** Each database now has both a `database_id` and a `data_source_id`\n  - Use `database_id` when creating pages (`parent: {\"database_id\": \"...\"}`)\n  - Use `data_source_id` when querying (`POST /v1/data_sources/{id}/query`)\n- **Search results:** Databases return as `\"object\": \"data_source\"` with their `data_source_id`\n- **Parent in responses:** Pages show `parent.data_source_id` alongside `parent.database_id`\n- **Finding the data_source_id:** Search for the database, or call `GET /v1/data_sources/{data_source_id}`\n\n## Notes\n\n- Page/database IDs are UUIDs (with or without dashes)\n- The API cannot set database view filters — that's UI-only\n- Rate limit: ~3 requests/second average\n- Use `is_inline: true` when creating data sources to embed them in pages\n","tags":{"latest":"1.0.0"},"stats":{"comments":3,"downloads":92779,"installsAllTime":2422,"installsCurrent":2417,"stars":260,"versions":1},"createdAt":1767545360889,"updatedAt":1778485729679},"latestVersion":{"version":"1.0.0","createdAt":1767545360889,"changelog":"","license":null},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"steipete","userId":"s179zksw999xz8ms4cy7pb2fr183m5jq","displayName":"Peter Steinberger","image":"https://avatars.githubusercontent.com/u/58493?v=4"},"moderation":null}