{"skill":{"slug":"openclaw-notion-api","displayName":"Openclaw Notion Api","summary":"Notion API 用于创建和管理页面、数据库和块。包含正确的图片、文件上传功能","description":"---\nname: openclaw-notion-api\ndescription: Notion API 用于创建和管理页面、数据库和块。包含正确的图片、文件上传功能\nhomepage: https://developers.notion.com\nauthor: ionepub\nmetadata: {\"clawdbot\":{\"emoji\":\"📝\"}}\n---\n\n# openclaw-notion-api\n\n使用 Notion API 创建/读取/更新页面、数据源（数据库）和块。\n\n## Setup（设置）\n\n1. 在 https://www.notion.so/profile/integrations/internal 创建内部集成\n2. 复制 API 密钥（以 `ntn_` 或 `secret_` 开头）\n3. 存储密钥：\n```bash\nmkdir -p ~/.config/notion\necho \"ntn_your_key_here\" > ~/.config/notion/api_key\n```\n4. 将目标页面/数据库与集成共享（点击 \"...\" → \"Connect to\" → 你的集成名称）\n\n## API Basics（API 基础）\n\n所有请求都需要：\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> **注意：** `Notion-Version` header 是必需的。本技能使用 `2025-09-03`（最新版本）。在此版本中，数据库在 API 中称为\"数据源\"。\n\n## Common Operations（常用操作）\n\n**搜索页面和数据源：**\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**获取页面：**\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**获取页面内容（块）：**\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**在数据源中创建页面：**\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\": \"xxxxxx\"},\n    \"properties\": {\n      \"Name\": {\"title\": [{\"text\": {\"content\": \"New Item\"}}]},\n      \"Status\": {\"select\": {\"name\": \"Todo\"}}\n    }\n  }'\n```\n\n**查询数据源（数据库）：**\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**创建数据源（数据库）：**\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**更新页面属性：**\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**向页面添加块：**\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      {\"type\": \"paragraph\", \"paragraph\": {\"rich_text\": [{\"text\": {\"content\": \"Hello\"}}]}}\n    ]\n  }'\n```\n\n## Property Types（属性类型）\n\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\": \"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（2025-09-03 版本的关键差异）\n\n- **数据库 → 数据源：** 使用 `/data_sources/` 端点进行查询和检索\n- **双 ID：** 每个数据库现在同时拥有 `database_id` 和 `data_source_id`\n  - 创建页面时使用 `database_id`（`parent: {\"database_id\": \"...\"}`）\n  - 查询时使用 `data_source_id`（`POST /v1/data_sources/{id}/query`）\n- **搜索结果：** 数据库以 `\"object\": \"data_source\"` 形式返回，并带有其 `data_source_id`\n- **响应中的父级：** 页面显示 `parent.data_source_id` 以及 `parent.database_id`\n- **查找 data_source_id：** 搜索数据库，或调用 `GET /v1/data_sources/{data_source_id}`\n\n## File Upload（文件上传）\n\n使用 Direct Upload 方法上传图片或文件到 Notion（文件大小不超过 20MB）。两者的步骤完全相同，仅在 Step 3 的块类型上有区别。\n\n### Step 1: Create File Upload Object（创建文件上传对象）\n\n创建上传对象以获取上传 URL：\n```bash\ncurl --request POST \\\n  --url 'https://api.notion.com/v1/file_uploads' \\\n  -H \"Authorization: Bearer $NOTION_KEY\" \\\n  -H 'Content-Type: application/json' \\\n  -H 'Notion-Version: 2025-09-03' \\\n  --data '{}'\n```\n\n响应包含：\n- `id`：文件上传 ID（在步骤 3 中使用）\n- `upload_url`：上传文件内容的 URL\n\n### Step 2: Upload File Content（上传文件内容）\n\n使用 multipart/form-data 上传实际的文件：\n```bash\ncurl --request POST \\\n  --url 'https://api.notion.com/v1/file_uploads/{file_upload_id}/send' \\\n  -H \"Authorization: Bearer $NOTION_KEY\" \\\n  -H 'Notion-Version: 2025-09-03' \\\n  -H 'Content-Type: multipart/form-data' \\\n  -F \"file=@/path/to/file.png\"\n```\n\n**重要：**\n- 使用 `POST` 方法（不是 PUT）\n- 包含 `Authorization` 和 `Notion-Version` headers\n- 使用 `-F` 进行 multipart/form-data\n- 文件大小必须 ≤ 20MB\n\n### Step 3: Insert into Page（插入到页面）\n\n将上传的文件作为块添加。根据文件类型选择不同的块类型：\n\n**上传图片：**\n```bash\ncurl --request PATCH \\\n  --url \"https://api.notion.com/v1/blocks/{page_id}/children\" \\\n  -H \"Authorization: Bearer $NOTION_KEY\" \\\n  -H 'Content-Type: application/json' \\\n  -H 'Notion-Version: 2025-09-03' \\\n  --data '{\n    \"children\": [\n      {\n        \"type\": \"image\",\n        \"image\": {\n          \"type\": \"file_upload\",\n          \"file_upload\": {\n            \"id\": \"{file_upload_id}\"\n          }\n        }\n      }\n    ]\n  }'\n```\n\n**上传文件：**\n```bash\ncurl --request PATCH \\\n  --url \"https://api.notion.com/v1/blocks/{page_id}/children\" \\\n  -H \"Authorization: Bearer $NOTION_KEY\" \\\n  -H 'Content-Type: application/json' \\\n  -H 'Notion-Version: 2025-09-03' \\\n  --data '{\n    \"children\": [\n      {\n        \"type\": \"file\",\n        \"file\": {\n          \"type\": \"file_upload\",\n          \"file_upload\": {\n            \"id\": \"{file_upload_id}\"\n          }\n        }\n      }\n    ]\n  }'\n```\n\n**注意：** 不要在块定义中包含 `\"object\": \"block\"`。\n\n### Common Errors（常见错误）\n\n- **invalid_request_url**：检查是否使用了 `POST` 方法和正确的 URL 格式\n- **unauthorized**：确保步骤 2 中存在 `Authorization` 和 `Notion-Version` headers\n- **validation_error**：必须在附加（步骤 3）之前上传文件（步骤 2）\n\n## Notes（注意事项）\n\n- 页面/数据库 ID 是 UUID（带或不带连字符）\n- API 无法设置数据库视图过滤器 — 这是 UI 专属功能\n- 速率限制：平均约 3 请求/秒\n- 创建数据源时使用 `is_inline: true` 以将其嵌入页面中\n","tags":{"latest":"0.1.0"},"stats":{"comments":0,"downloads":707,"installsAllTime":1,"installsCurrent":1,"stars":0,"versions":1},"createdAt":1772037135570,"updatedAt":1778491640561},"latestVersion":{"version":"0.1.0","createdAt":1772037135570,"changelog":"Initial release of openclaw-notion-api skill.\n\n- Provides guides and sample curl commands for Notion API operations including creating, reading, and updating pages, databases (data sources), and blocks.\n- Documents 2025-09-03 API changes: databases are now \"data sources\", with new endpoints and dual IDs.\n- Includes detailed instructions and examples for uploading and attaching files or images (<20MB) via Notion’s new direct file upload method.\n- Lists common property types and demonstrates their API payload formats.\n- Details common error scenarios and provides setup instructions for Notion API authentication.","license":null},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"ionepub","userId":"s17bh9vw6sv1y3h75fxg4518m5885j0z","displayName":"ionepub","image":"https://avatars.githubusercontent.com/u/16647246?v=4"},"moderation":null}