Notion API Integration
Notion API 集成构建与调试工具
安装使用
复制下面这段提示词发给你的 AI（Claude / Cursor / TRAE / Codex / WorkBuddy 等），它会自动帮你完成安装：
帮我安装这个 AI Skill：Notion API Integration。 它的用途是：Notion API 集成构建与调试工具 完整的 Skill 内容见：https://321skill.com/skills/notion-api-integration-x-2/raw/index.md 请读取该页面内容，如果是 SKILL.md 格式直接安装，如果是 README 提炼核心 prompt 后安装。
提示词包含完整的 Skill 内容链接，AI 读取后即可完成安装。你也可以 查看完整内容 确认无误。
使用示例
'我通过 curl 调用 Notion API 查询数据库，返回了 400 validation_error，错误信息是 "body failed validation: body.query.filter.and.and"，请帮我修复。' 它会分析过滤条件语法错误，指出 and 数组内不能嵌套 and，建议使用 "or" 或调整结构，并提供修正后的 curl 命令。
介绍
这个 Skill 专门解决 Notion API 集成中的各种实际问题：从数据源、页面、块、属性、过滤器、文件、Webhook 到批量导入，覆盖了调用 api.notion.com 时可能遇到的几乎所有异常场景。当请求返回 404（对象明明存在却报错）、400（validation_error）、401 或 429 限流时，当数据库查询返回错误行数或为空、结果被截断到 100 条、关联或回滚字段只返回部分条目时，当属性名或 Select 选项不匹配、Notion-Version 升级导致 database_id 变成 data_source_id 时，这个 Skill 都能提供精准的排查和修复指导。
使用方式非常灵活：你可以直接在对话中粘贴代码片段、curl 命令或 SDK 调用日志，描述你遇到的具体错误现象，Skill 会分析问题根源并给出修复方案，包括调整 filter 参数、修改分页逻辑、处理版本迁移、更新 OAuth 流程等。它也支持场景化提问，比如“如何将 CSV 数据导入 Notion 工作区”或“怎样通过 Webhook 同步外部系统到 Notion”。
适合需要频繁与 Notion API 打交道的开发者、数据分析师和自动化工程师。无论是搭建内部集成工具、批量回填属性、同步数据到外部系统，还是处理文件上传/附件，这个 Skill 都能显著减少试错时间。
注意：本 Skill 专注于 Notion API 的集成和调试，不涉及日历重排（notion-calendar）、跨应用笔记（notes）或通用 REST/OAuth 机制（api）。如果你需要的是通用 HTTP 请求调试或 OAuth 流程，请使用专门的 API 工具。建议在使用前准备好 Notion 内部集成令牌或 OAuth 凭据，以及相关的 API 版本号。
核心特点
与通用 API 调试工具不同，这个 Skill 专门针对 Notion 的 400/401/404/429 等典型错误、数据库查询结果异常、版本升级兼容性、关联/回滚字段部分缺失等具体场景，而非泛泛的 REST 或 OAuth 指导。
注意事项
不适用于日历重排、跨应用笔记写作、通用 REST/OAuth 调试等非 Notion 特定场景。
常见问题
Notion API 返回 429 限流怎么办？
检查请求频率，增加重试逻辑，或者使用批量导入减少请求次数。Skill 可以帮你分析限流原因并给出优化建议。
数据库查询结果为什么只有 100 条？
Notion API 默认分页大小为 100，需要设置 page_size 参数并使用 next_cursor 进行分页获取全部数据。
给 AI 助手的安装指引
如果你的 AI 编程助手（Claude Code、Cursor、TRAE 等）能看到这个页面，把下面这段发给它即可自动完成安装：
请访问 https://321skill.com/skills/notion-api-integration-x-2/raw/index.md 读取 Notion API Integration 的原始 Skill 定义（Markdown 格式），按其中说明在我的环境里完成安装和配置。
AI 可直接读取的原始 Markdown 地址：/skills/notion-api-integration-x-2/raw/index.md（查看排版版本）