notion-openapi-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Notion Public API Skill

Notion Public API 技能

Use this skill to run Notion Public API operations through

uxc

+ OpenAPI.

Reuse the

uxc

skill for shared execution, OAuth, and error-handling guidance.

使用本技能可通过

uxc

+ OpenAPI执行Notion Public API操作。

复用

uxc

技能实现共享执行、OAuth和错误处理。

Prerequisites

前置条件

```
uxc
```
is installed and available in
```
PATH
```
.
Network access to
```
https://api.notion.com/v1
```
.

Access to the curated OpenAPI schema URL:

https://raw.githubusercontent.com/holon-run/uxc/main/skills/notion-openapi-skill/references/notion-public.openapi.json

A Notion integration token or OAuth credential with content read access.
For writes, the integration also needs the corresponding Notion insert/update content capabilities.

已安装
```
uxc
```
并可在
```
PATH
```
中访问。
可访问
```
https://api.notion.com/v1
```
的网络权限。

可访问精选OpenAPI schema的URL：

https://raw.githubusercontent.com/holon-run/uxc/main/skills/notion-openapi-skill/references/notion-public.openapi.json

具备内容读取权限的Notion集成令牌或OAuth凭证。
若需写入操作，集成还需具备对应的Notion插入/更新内容权限。

Scope

适用范围

This skill covers a read-first Notion REST surface focused on traversal plus common content writes:

token identity validation
title search for pages, data sources, and databases
page lookup
block lookup
recursive traversal via block-children pagination
page property retrieval
page creation
page updates, including trash/restore via
```
in_trash
```
block append
block updates
block deletion
data source retrieval and query
legacy database retrieval and query

This skill does not cover:

full Notion REST coverage
comments, file uploads, webhooks, page move, or schema mutation
automatic recursive traversal loops inside one single command

本技能涵盖以读取为主的Notion REST操作面，聚焦遍历功能及常见内容写入：

令牌身份验证
页面、数据源和数据库的标题搜索
页面查询
块查询
通过块子节点分页实现递归遍历
页面属性获取
页面创建
页面更新（包括通过
```
in_trash
```
进行删除/恢复）
块追加
块更新
块删除
数据源获取与查询
旧版数据库获取与查询

本技能不涵盖：

Notion REST API的完整功能
评论、文件上传、Webhook、页面移动或架构变更
单条命令内的自动递归遍历循环

Endpoint And Version

端点与版本

base URL:
```
https://api.notion.com/v1
```
required version header for this skill:
```
Notion-Version: 2026-03-11
```

The schema is intentionally curated around traversal and schema discovery. It is not a full dump of the Notion API.

基础URL：
```
https://api.notion.com/v1
```
本技能要求的版本头：
```
Notion-Version: 2026-03-11
```

该schema围绕遍历和架构发现精心筛选，并非Notion API的完整导出。

Authentication

身份验证

Notion Public API requires:

```
Authorization: Bearer <token>
```
```
Notion-Version: 2026-03-11
```

Notion Public API要求：

```
Authorization: Bearer <token>
```
```
Notion-Version: 2026-03-11
```

Recommended: dedicated REST credential

推荐：专用REST凭证

If you already have an internal integration token:

bash

uxc auth credential set notion-openapi \
  --auth-type api_key \
  --header "Authorization=Bearer {{secret}}" \
  --header "Notion-Version=2026-03-11" \
  --secret-env NOTION_API_TOKEN

uxc auth binding add \
  --id notion-openapi \
  --host api.notion.com \
  --path-prefix /v1 \
  --scheme https \
  --credential notion-openapi \
  --priority 100

How to get the internal integration token:

Open the Notion integrations dashboard and create an internal integration for your workspace.
In the integration configuration page, copy the API secret shown by Notion.
In Notion UI, open each target page, data source, or database and add this integration via
```
Share
```
or
```
Connections
```
.
Use that API secret as
```
NOTION_API_TOKEN
```
or pass it directly to
```
uxc auth credential set
```
.

Without connecting the integration to the target content, REST calls may authenticate successfully but still fail with access errors or return incomplete search results.

If you want OAuth-managed tokens for the REST host:

bash

uxc auth oauth start notion-openapi \
  --endpoint https://api.notion.com/v1 \
  --redirect-uri http://127.0.0.1:8788/callback \
  --client-id <client_id> \
  --scope read

uxc auth oauth complete notion-openapi \
  --session-id <session_id> \
  --authorization-response 'http://127.0.0.1:8788/callback?code=...'

uxc auth credential set notion-openapi \
  --auth-type oauth \
  --header "Authorization=Bearer {{secret}}" \
  --header "Notion-Version=2026-03-11"

uxc auth binding add \
  --id notion-openapi \
  --host api.notion.com \
  --path-prefix /v1 \
  --scheme https \
  --credential notion-openapi \
  --priority 100

若已拥有内部集成令牌：

bash

uxc auth credential set notion-openapi \
  --auth-type api_key \
  --header "Authorization=Bearer {{secret}}" \
  --header "Notion-Version=2026-03-11" \
  --secret-env NOTION_API_TOKEN

uxc auth binding add \
  --id notion-openapi \
  --host api.notion.com \
  --path-prefix /v1 \
  --scheme https \
  --credential notion-openapi \
  --priority 100

获取内部集成令牌的方法：

打开Notion集成控制台，为你的工作区创建一个内部集成。
在集成配置页面，复制Notion显示的API密钥。
在Notion界面中，打开每个目标页面、数据源或数据库，通过「共享」或「连接」添加该集成。
将该API密钥作为
```
NOTION_API_TOKEN
```
使用，或直接传入
```
uxc auth credential set
```
命令。

若未将集成连接到目标内容，REST调用可能验证成功，但仍会出现访问错误或返回不完整的搜索结果。

若要为REST主机使用OAuth管理的令牌：

bash

uxc auth oauth start notion-openapi \
  --endpoint https://api.notion.com/v1 \
  --redirect-uri http://127.0.0.1:8788/callback \
  --client-id <client_id> \
  --scope read

uxc auth oauth complete notion-openapi \
  --session-id <session_id> \
  --authorization-response 'http://127.0.0.1:8788/callback?code=...'

uxc auth credential set notion-openapi \
  --auth-type oauth \
  --header "Authorization=Bearer {{secret}}" \
  --header "Notion-Version=2026-03-11"

uxc auth binding add \
  --id notion-openapi \
  --host api.notion.com \
  --path-prefix /v1 \
  --scheme https \
  --credential notion-openapi \
  --priority 100

Advanced: reuse the same OAuth credential as

notion-mcp

进阶：复用

notion-mcp

的同一OAuth凭证

This is technically possible in

uxc

if the existing credential already has a valid Notion OAuth access token.

Important:

once an OAuth credential uses custom headers, include
```
Authorization=Bearer {{secret}}
```
explicitly
adding
```
Notion-Version=2026-03-11
```
on the shared credential means the same header will also be sent to
```
mcp.notion.com/mcp
```
that extra header is expected to be harmless, but this is an interoperability assumption rather than an explicit Notion guarantee

Shared-credential setup:

bash

uxc auth credential set notion-mcp \
  --auth-type oauth \
  --header "Authorization=Bearer {{secret}}" \
  --header "Notion-Version=2026-03-11"

uxc auth binding add \
  --id notion-openapi-shared \
  --host api.notion.com \
  --path-prefix /v1 \
  --scheme https \
  --credential notion-mcp \
  --priority 100

Validate the effective mapping when auth looks wrong:

bash

uxc auth binding match https://api.notion.com/v1

若现有凭证已具备有效的Notion OAuth访问令牌，在

uxc

中可实现此操作。

注意事项：

一旦OAuth凭证使用自定义头，需显式包含
```
Authorization=Bearer {{secret}}
```
在共享凭证中添加
```
Notion-Version=2026-03-11
```
意味着该头也会发送到
```
mcp.notion.com/mcp
```
额外的头预计不会造成问题，但这是互操作性假设而非Notion的明确保证

共享凭证设置：

bash

uxc auth credential set notion-mcp \
  --auth-type oauth \
  --header "Authorization=Bearer {{secret}}" \
  --header "Notion-Version=2026-03-11"

uxc auth binding add \
  --id notion-openapi-shared \
  --host api.notion.com \
  --path-prefix /v1 \
  --scheme https \
  --credential notion-mcp \
  --priority 100

当身份验证出现问题时，验证有效映射：

bash

uxc auth binding match https://api.notion.com/v1

Core Workflow

核心工作流程

Use the fixed link command by default:

```
command -v notion-openapi-cli
```

If missing, create it:

uxc link notion-openapi-cli https://api.notion.com/v1 --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/notion-openapi-skill/references/notion-public.openapi.json

```
notion-openapi-cli -h
```

Inspect operation schema first:

```
notion-openapi-cli post:/search -h
```

notion-openapi-cli get:/blocks/{block_id}/children -h

```
notion-openapi-cli post:/pages -h
```

notion-openapi-cli patch:/blocks/{block_id}/children -h

notion-openapi-cli post:/data_sources/{data_source_id}/query -h

Prefer read validation before broader traversal:

```
notion-openapi-cli get:/users/me
```

notion-openapi-cli post:/search '{"query":"Roadmap","filter":{"property":"object","value":"page"},"page_size":10}'

notion-openapi-cli get:/blocks/{block_id}/children block_id=<uuid> page_size=100

Traverse recursively outside the API call boundary:
- use
```
get:/blocks/{block_id}/children
```
  page by page
- for every returned child block with
```
has_children=true
```
  , call
```
get:/blocks/{block_id}/children
```
  again on that child ID

Use data source or legacy database reads to discover schema before property-sensitive queries:

notion-openapi-cli get:/data_sources/{data_source_id} data_source_id=<uuid>

notion-openapi-cli post:/data_sources/{data_source_id}/query data_source_id=<uuid> '{"page_size":25}'

notion-openapi-cli get:/databases/{database_id} database_id=<uuid>

Execute writes only after explicit user confirmation:

create page:
```
notion-openapi-cli post:/pages '{...}'
```

append blocks:

notion-openapi-cli patch:/blocks/{block_id}/children '{...}'

update page or block:

notion-openapi-cli patch:/pages/{page_id} '{...}'

delete block:

notion-openapi-cli delete:/blocks/{block_id} block_id=<uuid>

默认使用固定链接命令：

```
command -v notion-openapi-cli
```

若未找到，创建链接：

uxc link notion-openapi-cli https://api.notion.com/v1 --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/notion-openapi-skill/references/notion-public.openapi.json

```
notion-openapi-cli -h
```

先检查操作schema：

```
notion-openapi-cli post:/search -h
```

notion-openapi-cli get:/blocks/{block_id}/children -h

```
notion-openapi-cli post:/pages -h
```

notion-openapi-cli patch:/blocks/{block_id}/children -h

notion-openapi-cli post:/data_sources/{data_source_id}/query -h

在进行大范围遍历前优先验证读取功能：

```
notion-openapi-cli get:/users/me
```

notion-openapi-cli post:/search '{"query":"Roadmap","filter":{"property":"object","value":"page"},"page_size":10}'

notion-openapi-cli get:/blocks/{block_id}/children block_id=<uuid> page_size=100

在API调用边界外执行递归遍历：
- 逐页使用
```
get:/blocks/{block_id}/children
```
- 对于每个返回的
```
has_children=true
```
  子块，再次调用
```
get:/blocks/{block_id}/children
```
  并传入该子块ID

在执行属性敏感查询前，先通过数据源或旧版数据库读取发现架构：

notion-openapi-cli get:/data_sources/{data_source_id} data_source_id=<uuid>

notion-openapi-cli post:/data_sources/{data_source_id}/query data_source_id=<uuid> '{"page_size":25}'

notion-openapi-cli get:/databases/{database_id} database_id=<uuid>

仅在用户明确确认后执行写入操作：

创建页面：
```
notion-openapi-cli post:/pages '{...}'
```

追加块：

notion-openapi-cli patch:/blocks/{block_id}/children '{...}'

更新页面或块：

notion-openapi-cli patch:/pages/{page_id} '{...}'

删除块：

notion-openapi-cli delete:/blocks/{block_id} block_id=<uuid>

Operation Groups

操作分组

Session / Discovery

会话 / 发现

```
get:/users/me
```
```
post:/search
```

```
get:/users/me
```
```
post:/search
```

Page And Block Traversal

页面与块遍历

```
get:/pages/{page_id}
```

get:/pages/{page_id}/properties/{property_id}

```
get:/blocks/{block_id}
```
```
get:/blocks/{block_id}/children
```

```
get:/pages/{page_id}
```

get:/pages/{page_id}/properties/{property_id}

```
get:/blocks/{block_id}
```
```
get:/blocks/{block_id}/children
```

Page And Block Writes

页面与块写入

```
post:/pages
```
```
patch:/pages/{page_id}
```
```
patch:/blocks/{block_id}/children
```
```
patch:/blocks/{block_id}
```
```
delete:/blocks/{block_id}
```

```
post:/pages
```
```
patch:/pages/{page_id}
```
```
patch:/blocks/{block_id}/children
```
```
patch:/blocks/{block_id}
```
```
delete:/blocks/{block_id}
```

Data Source Reads

数据源读取

```
get:/data_sources/{data_source_id}
```

post:/data_sources/{data_source_id}/query

```
get:/data_sources/{data_source_id}
```

post:/data_sources/{data_source_id}/query

Legacy Database Reads

旧版数据库读取

```
get:/databases/{database_id}
```
```
post:/databases/{database_id}/query
```

```
get:/databases/{database_id}
```
```
post:/databases/{database_id}/query
```

Guardrails

注意事项

Keep automation on the JSON output envelope; do not use
```
--text
```
.
Parse stable fields first:
```
ok
```
,
```
kind
```
,
```
protocol
```
,
```
data
```
,
```
error
```
.
This skill fixes
```
Notion-Version
```
at the credential/header layer instead of requiring it as an operation argument. Keep the credential header on
```
2026-03-11
```
unless you intentionally migrate the whole skill surface.

This skill is read-first, but it now includes common content writes. Always confirm intent before

post:/pages

patch:/pages/{page_id}

patch:/blocks/{block_id}/children

patch:/blocks/{block_id}

, or

delete:/blocks/{block_id}

On Notion API version
```
2026-03-11
```
,
```
archived
```
has been replaced by
```
in_trash
```
for request and response semantics. Prefer
```
in_trash
```
in update payloads.
```
patch:/blocks/{block_id}/children
```
supports up to 100 new children in one request and up to two levels of nested blocks in a single payload.
```
patch:/blocks/{block_id}
```
updates block content, but it does not update child lists. Use
```
patch:/blocks/{block_id}/children
```
to append nested content.
Prefer
```
data_sources
```
endpoints over legacy
```
databases
```
endpoints for new workflows. Keep legacy database reads only for compatibility with older shared links and IDs.
```
get:/blocks/{block_id}/children
```
returns only one nesting level at a time. Recursive traversal must be performed by repeated calls.
Notion may return fewer results than
```
page_size
```
; always check
```
has_more
```
and
```
next_cursor
```
.

notion-openapi-cli <operation> ...

is equivalent to

uxc https://api.notion.com/v1 --schema-url <notion_openapi_schema> <operation> ...

仅对JSON输出包执行自动化操作，请勿使用
```
--text
```
参数。
优先解析稳定字段：
```
ok
```
,
```
kind
```
,
```
protocol
```
,
```
data
```
,
```
error
```
。
本技能在凭证/头层级固定
```
Notion-Version
```
，无需将其作为操作参数。除非有意迁移整个技能操作面，否则请保持凭证头为
```
2026-03-11
```
。
本技能以读取为主，但目前已包含常见内容写入操作。执行
```
post:/pages
```
、
```
patch:/pages/{page_id}
```
、
```
patch:/blocks/{block_id}/children
```
、
```
patch:/blocks/{block_id}
```
或
```
delete:/blocks/{block_id}
```
前，务必确认操作意图。
在Notion API版本
```
2026-03-11
```
中，
```
archived
```
已被
```
in_trash
```
替代，用于请求和响应语义。在更新负载中优先使用
```
in_trash
```
。
```
patch:/blocks/{block_id}/children
```
单次请求最多支持100个新子块，单个负载最多支持两层嵌套块。
```
patch:/blocks/{block_id}
```
用于更新块内容，但不更新子列表。如需追加嵌套内容，请使用
```
patch:/blocks/{block_id}/children
```
。
对于新工作流，优先使用
```
data_sources
```
端点而非旧版
```
databases
```
端点。仅为兼容旧共享链接和ID保留旧版数据库读取功能。
```
get:/blocks/{block_id}/children
```
仅返回一级嵌套内容。递归遍历需通过重复调用实现。
Notion返回的结果可能少于
```
page_size
```
指定数量；请始终检查
```
has_more
```
和
```
next_cursor
```
。

notion-openapi-cli <operation> ...

等价于

uxc https://api.notion.com/v1 --schema-url <notion_openapi_schema> <operation> ...

。

References

参考资料

Usage patterns:
```
references/usage-patterns.md
```
Curated OpenAPI schema:
```
references/notion-public.openapi.json
```
Notion API reference: https://developers.notion.com/reference
Retrieve a database: https://developers.notion.com/reference/retrieve-a-database
Retrieve a block: https://developers.notion.com/reference/retrieve-a-block
Versioning: https://developers.notion.com/reference/versioning

使用模式：
```
references/usage-patterns.md
```
精选OpenAPI schema：
```
references/notion-public.openapi.json
```
Notion API参考：https://developers.notion.com/reference
获取数据库：https://developers.notion.com/reference/retrieve-a-database
获取块：https://developers.notion.com/reference/retrieve-a-block
版本控制：https://developers.notion.com/reference/versioning

notion-openapi-skill

Original

Translation

Notion Public API Skill

Notion Public API 技能

Prerequisites

前置条件

Scope

适用范围

Endpoint And Version

端点与版本

Authentication

身份验证

Recommended: dedicated REST credential

推荐：专用REST凭证

Advanced: reuse the same OAuth credential as
`notion-mcp`

进阶：复用
`notion-mcp`
的同一OAuth凭证

Core Workflow

核心工作流程

Operation Groups

操作分组

Session / Discovery

会话 / 发现

Page And Block Traversal

页面与块遍历

Page And Block Writes

页面与块写入

Data Source Reads

数据源读取

Legacy Database Reads

旧版数据库读取

Guardrails

注意事项

References

参考资料

notion-openapi-skill

Original

Translation

Notion Public API Skill

Notion Public API 技能

Prerequisites

前置条件

Scope

适用范围

Endpoint And Version

端点与版本

Authentication

身份验证

Recommended: dedicated REST credential

推荐：专用REST凭证

Advanced: reuse the same OAuth credential as notion-mcp

进阶：复用notion-mcp的同一OAuth凭证

Core Workflow

核心工作流程

Operation Groups

操作分组

Session / Discovery

会话 / 发现

Page And Block Traversal

页面与块遍历

Page And Block Writes

页面与块写入

Data Source Reads

数据源读取

Legacy Database Reads

旧版数据库读取

Guardrails

注意事项

References

参考资料

Advanced: reuse the same OAuth credential as
`notion-mcp`

进阶：复用
`notion-mcp`
的同一OAuth凭证