读取页面正文并追加段落

页面属性不含完整正文；用内容块接口读取与追加正文。

官方资料核对 2026-10-15示例代码，未进行真实接口实测

接入准备

Read content 用于读取，Insert content 用于追加；二者需分别启用。
连接已获目标页面访问权限。

准备环境变量

示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行；密钥不应放进公开网页。

NOTION_TOKEN: 内部 connection 的 API Secret；在页面连接菜单授予访问，不是登录 Cookie。
NOTION_PAGE_ID: 真实页面 ID，示例是假 UUID。

export NOTION_TOKEN='replace_with_internal_connection_token'
export NOTION_PAGE_ID='22222222-2222-4222-8222-222222222222'

以上 export 适用于 macOS / Linux 的终端，在同一终端内运行后续代码。Python 示例保存为 request.py 后执行 python3 request.py。

调用步骤

01
把页面 ID 保存到 NOTION_PAGE_ID。
02
先读取首层 blocks；有 has_more 时携带 next_cursor；遇到 has_children=true 的块，按其 block id 递归读取。
03
确认目标正确后执行追加，只新增测试段落，不更改已有块。

调用 01

读取第一层内容块

对页面使用 block children 接口；此请求不会递归展开子块。

GEThttps://api.notion.com/v1/blocks/${NOTION_PAGE_ID}/children?page_size=100

请求头

Authorization: Bearer ${NOTION_TOKEN}
Notion-Version: 2026-03-11
Content-Type: application/json

参数说明

参数表可左右滑动，查看完整说明。

字段 / 位置	类型 / 必填	说明
`block_id`Path	UUID必填	可传页面 ID，或允许包含子块的块 ID。
`page_size`Query	integer可选	最大 100。
`start_cursor`Query	string可选	从上次 next_cursor 取得，放 URL 前需编码。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误，业务状态还需按下方返回示例核对。

# 执行后核对返回 JSON 的业务状态；HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request GET \
  --url "https://api.notion.com/v1/blocks/${NOTION_PAGE_ID}/children?page_size=100" \
  --header "Authorization: Bearer ${NOTION_TOKEN}" \
  --header "Notion-Version: 2026-03-11" \
  --header "Content-Type: application/json"

import json
import os
import re
import urllib.request
import urllib.error

def expand(value):
    return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
                  lambda match: os.environ[match.group(1)], value)

url = expand("https://api.notion.com/v1/blocks/${NOTION_PAGE_ID}/children?page_size=100")
headers = {
    "Authorization": expand("Bearer ${NOTION_TOKEN}"),
    "Notion-Version": expand("2026-03-11"),
    "Content-Type": expand("application/json"),
}
data = None
request = urllib.request.Request(url, data=data, headers=headers, method="GET")
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))

// Node.js 22+，保存为 request.mjs 后运行 node request.mjs
function expand(value) {
  return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
    if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
    return process.env[name];
  });
}

const url = expand("https://api.notion.com/v1/blocks/${NOTION_PAGE_ID}/children?page_size=100");
const headers = Object.fromEntries(
  Object.entries({
  "Authorization": "Bearer ${NOTION_TOKEN}",
  "Notion-Version": "2026-03-11",
  "Content-Type": "application/json"
}).map(([key, value]) => [key, expand(value)])
);
const response = await fetch(url, {
  method: "GET",
  headers,
  signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));

返回示例

按官方字段整理的节选示意，使用虚构 ID，不是实测结果。结果位于 results；有子块时递归单独查询。以下为结构示意，非本站实测结果。

{
  "object": "list",
  "results": [
    {
      "object": "block",
      "id": "33333333-3333-4333-8333-333333333333",
      "type": "paragraph",
      "has_children": false,
      "paragraph": {
        "rich_text": [
          {
            "type": "text",
            "text": {
              "content": "已有正文"
            },
            "plain_text": "已有正文"
          }
        ]
      }
    }
  ],
  "next_cursor": null,
  "has_more": false
}

常见错误与排查

401 unauthorized令牌无效: 核对完整 Bearer Token 与 connection 状态。
403 restricted_resource连接权限不足: 开通所需 Read/Insert content capability，并核对资源授权。
404 object_not_found资源不存在或连接无权访问: 确认 ID 并在原始页面/数据库的 Connections 菜单添加连接。
429 rate_limited请求频率超过限制: 按 Retry-After 响应头等待后重试。

调用注意

每次只返回一层；忽略 has_children 会漏掉嵌套列表和子段落。

Retrieve block children

调用 02

在末尾追加段落

执行会新增正文；position=end 为当前插入位置写法，旧 after 字段已经弃用。

PATCHhttps://api.notion.com/v1/blocks/${NOTION_PAGE_ID}/children

请求头

Authorization: Bearer ${NOTION_TOKEN}
Notion-Version: 2026-03-11
Content-Type: application/json

参数说明

参数表可左右滑动，查看完整说明。

字段 / 位置	类型 / 必填	说明
`children`请求体	block[]必填	一次最多 100 个子块；一次最多两层嵌套。
`position`请求体	object可选	end 末尾（默认）、start 开头，或 after_block 指定已有块；不能同时传旧 after。
`children[].paragraph.rich_text`请求体	rich_text[]必填	paragraph 文本数组；单个 text.content 最长 2000 字符。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误，业务状态还需按下方返回示例核对。

cat > request-body.json <<'JSON'
{
  "children": [
    {
      "object": "block",
      "type": "paragraph",
      "paragraph": {
        "rich_text": [
          {
            "type": "text",
            "text": {
              "content": "这是一条通过 API 保存的测试记录。"
            }
          }
        ]
      }
    }
  ],
  "position": {
    "type": "end"
  }
}
JSON

# 执行后核对返回 JSON 的业务状态；HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request PATCH \
  --url "https://api.notion.com/v1/blocks/${NOTION_PAGE_ID}/children" \
  --header "Authorization: Bearer ${NOTION_TOKEN}" \
  --header "Notion-Version: 2026-03-11" \
  --header "Content-Type: application/json" \
  --data-binary @request-body.json

import json
import os
import re
import urllib.request
import urllib.error

def expand(value):
    return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
                  lambda match: os.environ[match.group(1)], value)

url = expand("https://api.notion.com/v1/blocks/${NOTION_PAGE_ID}/children")
headers = {
    "Authorization": expand("Bearer ${NOTION_TOKEN}"),
    "Notion-Version": expand("2026-03-11"),
    "Content-Type": expand("application/json"),
}
body = {
    "children": [
        {
            "object": "block",
            "type": "paragraph",
            "paragraph": {
                "rich_text": [
                    {
                        "type": "text",
                        "text": {
                            "content": "这是一条通过 API 保存的测试记录。",
                        },
                    },
                ],
            },
        },
    ],
    "position": {
        "type": "end",
    },
}
data = json.dumps(body, ensure_ascii=False).encode("utf-8")
request = urllib.request.Request(url, data=data, headers=headers, method="PATCH")
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))

// Node.js 22+，保存为 request.mjs 后运行 node request.mjs
function expand(value) {
  return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
    if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
    return process.env[name];
  });
}

const url = expand("https://api.notion.com/v1/blocks/${NOTION_PAGE_ID}/children");
const headers = Object.fromEntries(
  Object.entries({
  "Authorization": "Bearer ${NOTION_TOKEN}",
  "Notion-Version": "2026-03-11",
  "Content-Type": "application/json"
}).map(([key, value]) => [key, expand(value)])
);
const body = {
  "children": [
    {
      "object": "block",
      "type": "paragraph",
      "paragraph": {
        "rich_text": [
          {
            "type": "text",
            "text": {
              "content": "这是一条通过 API 保存的测试记录。"
            }
          }
        ]
      }
    }
  ],
  "position": {
    "type": "end"
  }
};
const response = await fetch(url, {
  method: "PATCH",
  headers,
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));

返回示例

按官方字段整理的节选示意，使用虚构 ID，不是实测结果。返回刚创建的一级块列表，保留每个块的 id。以下为结构示意，非本站实测结果。

{
  "object": "list",
  "results": [
    {
      "object": "block",
      "id": "44444444-4444-4444-8444-444444444444",
      "type": "paragraph",
      "has_children": false,
      "paragraph": {
        "rich_text": [
          {
            "type": "text",
            "text": {
              "content": "这是一条通过 API 保存的测试记录。"
            }
          }
        ]
      }
    }
  ],
  "next_cursor": null,
  "has_more": false
}

常见错误与排查

401 unauthorized令牌无效: 核对完整 Bearer Token 与 connection 状态。
403 restricted_resource连接权限不足: 开通所需 Read/Insert content capability，并核对资源授权。
404 object_not_found资源不存在或连接无权访问: 确认 ID 并在原始页面/数据库的 Connections 菜单添加连接。
429 rate_limited请求频率超过限制: 按 Retry-After 响应头等待后重试。

调用注意

本接口不能移动已有块；再次执行会再次追加，超时后应先读取确认再重试。
平均每个连接每秒 3 个请求；整包上限 500 KB，不能仅按 100 块判断能否提交。

Append block children Request limits

注意事项

按段落新增，不会清空页面；编辑已有内容应另用更新块接口。

核验来源

本站按官方资料整理本场景的必要调用步骤与代码，覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。

01
Create your first connection核验日期 2026-10-15
02
API versioning核验日期 2026-10-15
03
Request limits核验日期 2026-10-15
04
Retrieve block children核验日期 2026-10-15
05
Append block children核验日期 2026-10-15

Notion 数据 API的其他调用手册

在已授权页面下新建页面定位数据源并查询数据库条目

← 返回Notion 数据 API的全部功能