{“content”:”---\nname: notion\ndescription: Notion API for creating and managing pages, databases, and blocks via curl. Search, create, update, and query Notion workspaces directly from the terminal.\nversion: 1.0.0\nauthor: community\nlicense: MIT\nmetadata:\n hermes:\n tags: [Notion, Productivity, Notes, Database, API]\n homepage: https://developers.notion.com\nprerequisites:\n env_vars: [NOTION_API_KEY]\n---\n\n# Notion API\n\nUse the Notion API via curl to create, read, update pages, databases (data sources), and blocks. No extra tools needed — just curl and a Notion API key.\n\n## Prerequisites\n\n1. Create an integration at https://notion.so/my-integrations\n2. Copy the API key (starts with ntn_ or secret_)\n3. Store it in ~/.hermes/.env:\n \n NOTION_API_KEY=ntn_your_key_here\n \n4. Important: Share target pages/databases with your integration in Notion (click ”…” → “Connect to” → your integration name)\n\n## API Basics\n\nAll requests use this pattern:\n\nbash\ncurl -s -X GET \"https://api.notion.com/v1/...\" \\\n -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n -H \"Notion-Version: 2025-09-03\" \\\n -H \"Content-Type: application/json\"\n\n\nThe 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\n\nbash\ncurl -s -X POST \"https://api.notion.com/v1/search\" \\\n -H \"Authorization: Bearer $NOTION_API_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\nbash\ncurl -s \"https://api.notion.com/v1/pages/{page_id}\" \\\n -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n -H \"Notion-Version: 2025-09-03\"\n\n\n### Get Page Content (blocks)\n\nbash\ncurl -s \"https://api.notion.com/v1/blocks/{page_id}/children\" \\\n -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n -H \"Notion-Version: 2025-09-03\"\n\n\n### Create Page in a Database\n\nbash\ncurl -s -X POST \"https://api.notion.com/v1/pages\" \\\n -H \"Authorization: Bearer $NOTION_API_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 Database\n\nbash\ncurl -s -X POST \"https://api.notion.com/v1/data_sources/{data_source_id}/query\" \\\n -H \"Authorization: Bearer $NOTION_API_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 Database\n\nbash\ncurl -s -X POST \"https://api.notion.com/v1/data_sources\" \\\n -H \"Authorization: Bearer $NOTION_API_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\nbash\ncurl -s -X PATCH \"https://api.notion.com/v1/pages/{page_id}\" \\\n -H \"Authorization: Bearer $NOTION_API_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 Content to a Page\n\nbash\ncurl -s -X PATCH \"https://api.notion.com/v1/blocks/{page_id}/children\" \\\n -H \"Authorization: Bearer $NOTION_API_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 from Hermes!\"}}]}}\n ]\n }'\n\n\n## Property Types\n\nCommon property formats for database items:\n\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\": \"2026-01-15\", \"end\": \"2026-01-16\"}}\n- Checkbox: {\"checkbox\": true}\n- Number: {\"number\": 42}\n- URL: {\"url\": \"https://...\"}\n- Email: {\"email\": \"[email protected]\"}\n- Relation: {\"relation\": [{\"id\": \"page_id\"}]}\n\n## Key Differences in API Version 2025-09-03\n\n- Databases → Data Sources: Use /data_sources/ endpoints for queries and retrieval\n- Two IDs: Each database 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\n## Notes\n\n- Page/database IDs are UUIDs (with or without dashes)\n- Rate limit: ~3 requests/second average\n- The API cannot set database view filters — that’s UI-only\n- Use is_inline: true when creating data sources to embed them in pages\n- Add -s flag to curl to suppress progress bars (cleaner output for Hermes)\n- Pipe output through jq for readable JSON: ... | jq '.results[0].properties'\n”}