# Send Openclaw Notion Api to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "openclaw-notion-api",
    "name": "Openclaw Notion Api",
    "source": "tencent",
    "type": "skill",
    "category": "效率提升",
    "sourceUrl": "https://clawhub.ai/ionepub/openclaw-notion-api",
    "canonicalUrl": "https://clawhub.ai/ionepub/openclaw-notion-api",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/openclaw-notion-api",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=openclaw-notion-api",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "SKILL.md",
      "SKILL_en.md"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "slug": "openclaw-notion-api",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T17:15:36.049Z",
      "expiresAt": "2026-05-07T17:15:36.049Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=openclaw-notion-api",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=openclaw-notion-api",
        "contentDisposition": "attachment; filename=\"openclaw-notion-api-0.1.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "openclaw-notion-api"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/openclaw-notion-api"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/openclaw-notion-api",
    "downloadUrl": "https://openagent3.xyz/downloads/openclaw-notion-api",
    "agentUrl": "https://openagent3.xyz/skills/openclaw-notion-api/agent",
    "manifestUrl": "https://openagent3.xyz/skills/openclaw-notion-api/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/openclaw-notion-api/agent.md"
  }
}
```
## Documentation

### openclaw-notion-api

使用 Notion API 创建/读取/更新页面、数据源（数据库）和块。

### Setup（设置）

在 https://www.notion.so/profile/integrations/internal 创建内部集成
复制 API 密钥（以 ntn_ 或 secret_ 开头）
存储密钥：

mkdir -p ~/.config/notion
echo "ntn_your_key_here" > ~/.config/notion/api_key

将目标页面/数据库与集成共享（点击 "..." → "Connect to" → 你的集成名称）

### API Basics（API 基础）

所有请求都需要：

NOTION_KEY=$(cat ~/.config/notion/api_key)
curl -X GET "https://api.notion.com/v1/..." \\
  -H "Authorization: Bearer $NOTION_KEY" \\
  -H "Notion-Version: 2025-09-03" \\
  -H "Content-Type: application/json"

注意： Notion-Version header 是必需的。本技能使用 2025-09-03（最新版本）。在此版本中，数据库在 API 中称为"数据源"。

### Common Operations（常用操作）

搜索页面和数据源：

curl -X POST "https://api.notion.com/v1/search" \\
  -H "Authorization: Bearer $NOTION_KEY" \\
  -H "Notion-Version: 2025-09-03" \\
  -H "Content-Type: application/json" \\
  -d '{"query": "page title"}'

获取页面：

curl "https://api.notion.com/v1/pages/{page_id}" \\
  -H "Authorization: Bearer $NOTION_KEY" \\
  -H "Notion-Version: 2025-09-03"

获取页面内容（块）：

curl "https://api.notion.com/v1/blocks/{page_id}/children" \\
  -H "Authorization: Bearer $NOTION_KEY" \\
  -H "Notion-Version: 2025-09-03"

在数据源中创建页面：

curl -X POST "https://api.notion.com/v1/pages" \\
  -H "Authorization: Bearer $NOTION_KEY" \\
  -H "Notion-Version: 2025-09-03" \\
  -H "Content-Type: application/json" \\
  -d '{
    "parent": {"database_id": "xxxxxx"},
    "properties": {
      "Name": {"title": [{"text": {"content": "New Item"}}]},
      "Status": {"select": {"name": "Todo"}}
    }
  }'

查询数据源（数据库）：

curl -X POST "https://api.notion.com/v1/data_sources/{data_source_id}/query" \\
  -H "Authorization: Bearer $NOTION_KEY" \\
  -H "Notion-Version: 2025-09-03" \\
  -H "Content-Type: application/json" \\
  -d '{
    "filter": {"property": "Status", "select": {"equals": "Active"}},
    "sorts": [{"property": "Date", "direction": "descending"}]
  }'

创建数据源（数据库）：

curl -X POST "https://api.notion.com/v1/data_sources" \\
  -H "Authorization: Bearer $NOTION_KEY" \\
  -H "Notion-Version: 2025-09-03" \\
  -H "Content-Type: application/json" \\
  -d '{
    "parent": {"page_id": "xxx"},
    "title": [{"text": {"content": "My Database"}}],
    "properties": {
      "Name": {"title": {}},
      "Status": {"select": {"options": [{"name": "Todo"}, {"name": "Done"}]}},
      "Date": {"date": {}}
    }
  }'

更新页面属性：

curl -X PATCH "https://api.notion.com/v1/pages/{page_id}" \\
  -H "Authorization: Bearer $NOTION_KEY" \\
  -H "Notion-Version: 2025-09-03" \\
  -H "Content-Type: application/json" \\
  -d '{"properties": {"Status": {"select": {"name": "Done"}}}}'

向页面添加块：

curl -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" \\
  -H "Authorization: Bearer $NOTION_KEY" \\
  -H "Notion-Version: 2025-09-03" \\
  -H "Content-Type: application/json" \\
  -d '{
    "children": [
      {"type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Hello"}}]}}
    ]
  }'

### Property Types（属性类型）

数据库项的常用属性格式：

标题（Title）： {"title": [{"text": {"content": "..."}}]}
富文本（Rich text）： {"rich_text": [{"text": {"content": "..."}}]}
选择（Select）： {"select": {"name": "Option"}}
多选（Multi-select）： {"multi_select": [{"name": "A"}, {"name": "B"}]}
日期（Date）： {"date": {"start": "2024-01-15", "end": "2024-01-16"}}
复选框（Checkbox）： {"checkbox": true}
数字（Number）： {"number": 42}
URL： {"url": "https://..."}
邮箱（Email）： {"email": "a@b.com"}
关联（Relation）： {"relation": [{"id": "page_id"}]}

### Key Differences in 2025-09-03（2025-09-03 版本的关键差异）

数据库 → 数据源： 使用 /data_sources/ 端点进行查询和检索
双 ID： 每个数据库现在同时拥有 database_id 和 data_source_id

创建页面时使用 database_id（parent: {"database_id": "..."}）
查询时使用 data_source_id（POST /v1/data_sources/{id}/query）


搜索结果： 数据库以 "object": "data_source" 形式返回，并带有其 data_source_id
响应中的父级： 页面显示 parent.data_source_id 以及 parent.database_id
查找 data_source_id： 搜索数据库，或调用 GET /v1/data_sources/{data_source_id}

### File Upload（文件上传）

使用 Direct Upload 方法上传图片或文件到 Notion（文件大小不超过 20MB）。两者的步骤完全相同，仅在 Step 3 的块类型上有区别。

### Step 1: Create File Upload Object（创建文件上传对象）

创建上传对象以获取上传 URL：

curl --request POST \\
  --url 'https://api.notion.com/v1/file_uploads' \\
  -H "Authorization: Bearer $NOTION_KEY" \\
  -H 'Content-Type: application/json' \\
  -H 'Notion-Version: 2025-09-03' \\
  --data '{}'

响应包含：

id：文件上传 ID（在步骤 3 中使用）
upload_url：上传文件内容的 URL

### Step 2: Upload File Content（上传文件内容）

使用 multipart/form-data 上传实际的文件：

curl --request POST \\
  --url 'https://api.notion.com/v1/file_uploads/{file_upload_id}/send' \\
  -H "Authorization: Bearer $NOTION_KEY" \\
  -H 'Notion-Version: 2025-09-03' \\
  -H 'Content-Type: multipart/form-data' \\
  -F "file=@/path/to/file.png"

重要：

使用 POST 方法（不是 PUT）
包含 Authorization 和 Notion-Version headers
使用 -F 进行 multipart/form-data
文件大小必须 ≤ 20MB

### Step 3: Insert into Page（插入到页面）

将上传的文件作为块添加。根据文件类型选择不同的块类型：

上传图片：

curl --request PATCH \\
  --url "https://api.notion.com/v1/blocks/{page_id}/children" \\
  -H "Authorization: Bearer $NOTION_KEY" \\
  -H 'Content-Type: application/json' \\
  -H 'Notion-Version: 2025-09-03' \\
  --data '{
    "children": [
      {
        "type": "image",
        "image": {
          "type": "file_upload",
          "file_upload": {
            "id": "{file_upload_id}"
          }
        }
      }
    ]
  }'

上传文件：

curl --request PATCH \\
  --url "https://api.notion.com/v1/blocks/{page_id}/children" \\
  -H "Authorization: Bearer $NOTION_KEY" \\
  -H 'Content-Type: application/json' \\
  -H 'Notion-Version: 2025-09-03' \\
  --data '{
    "children": [
      {
        "type": "file",
        "file": {
          "type": "file_upload",
          "file_upload": {
            "id": "{file_upload_id}"
          }
        }
      }
    ]
  }'

注意： 不要在块定义中包含 "object": "block"。

### Common Errors（常见错误）

invalid_request_url：检查是否使用了 POST 方法和正确的 URL 格式
unauthorized：确保步骤 2 中存在 Authorization 和 Notion-Version headers
validation_error：必须在附加（步骤 3）之前上传文件（步骤 2）

### Notes（注意事项）

页面/数据库 ID 是 UUID（带或不带连字符）
API 无法设置数据库视图过滤器 — 这是 UI 专属功能
速率限制：平均约 3 请求/秒
创建数据源时使用 is_inline: true 以将其嵌入页面中
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: ionepub
- Version: 0.1.0
## Source health
- Status: healthy
- Item download looks usable.
- Yavira can redirect you to the upstream package for this item.
- Health scope: item
- Reason: direct_download_ok
- Checked at: 2026-04-30T17:15:36.049Z
- Expires at: 2026-05-07T17:15:36.049Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/openclaw-notion-api)
- [Send to Agent page](https://openagent3.xyz/skills/openclaw-notion-api/agent)
- [JSON manifest](https://openagent3.xyz/skills/openclaw-notion-api/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/openclaw-notion-api/agent.md)
- [Download page](https://openagent3.xyz/downloads/openclaw-notion-api)