在已授权页面下新建页面

使用内部连接创建子页面，可同时放入一段正文。

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

接入准备

在 Notion Developers 创建工作区内部 connection，开通 Insert content。
在父页面菜单 → Connections 中添加该连接；公开可浏览不等于 API 已授权。

准备环境变量

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

NOTION_TOKEN: 内部 connection 的 API Secret；在页面连接菜单授予访问，不是登录 Cookie。

export NOTION_TOKEN='replace_with_internal_connection_token'

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

调用步骤

01
取得 connection Secret 并放入 NOTION_TOKEN。
02
复制父页面链接中的 32 位 ID（可转为 UUID 形式），替换 body 的 parent.page_id。
03
执行请求，保存响应 id；后续读写正文使用这个新页面 ID。

调用 01

创建带正文的子页面

本例 parent 为普通页面，因此 properties 仅设置 title。body 的 UUID 为虚构值，须先替换。

POSThttps://api.notion.com/v1/pages

请求头

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

参数说明

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

字段 / 位置	类型 / 必填	说明
`Notion-Version`Header	string必填	固定 2026-03-11，避免与旧 database 模型混用。
`parent.page_id`请求体	UUID必填	内部连接必须指定已授权的页面或数据源父级，本例选择普通页面。
`properties.title.title`请求体	rich_text[]必填	子页面的标题内容；本例 parent 为页面，不能放任意数据库字段。
`children`请求体	block[]可选	可在创建时加入内容块；本例只含一个 paragraph。

调用代码

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

cat > request-body.json <<'JSON'
{
  "parent": {
    "type": "page_id",
    "page_id": "11111111-1111-4111-8111-111111111111"
  },
  "properties": {
    "title": {
      "type": "title",
      "title": [
        {
          "type": "text",
          "text": {
            "content": "API 接入测试"
          }
        }
      ]
    }
  },
  "children": [
    {
      "object": "block",
      "type": "paragraph",
      "paragraph": {
        "rich_text": [
          {
            "type": "text",
            "text": {
              "content": "这是一条通过 API 保存的测试记录。"
            }
          }
        ]
      }
    }
  ]
}
JSON

# 执行后核对返回 JSON 的业务状态；HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.notion.com/v1/pages" \
  --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/pages")
headers = {
    "Authorization": expand("Bearer ${NOTION_TOKEN}"),
    "Notion-Version": expand("2026-03-11"),
    "Content-Type": expand("application/json"),
}
body = {
    "parent": {
        "type": "page_id",
        "page_id": "11111111-1111-4111-8111-111111111111",
    },
    "properties": {
        "title": {
            "type": "title",
            "title": [
                {
                    "type": "text",
                    "text": {
                        "content": "API 接入测试",
                    },
                },
            ],
        },
    },
    "children": [
        {
            "object": "block",
            "type": "paragraph",
            "paragraph": {
                "rich_text": [
                    {
                        "type": "text",
                        "text": {
                            "content": "这是一条通过 API 保存的测试记录。",
                        },
                    },
                ],
            },
        },
    ],
}
data = json.dumps(body, ensure_ascii=False).encode("utf-8")
request = urllib.request.Request(url, data=data, headers=headers, method="POST")
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/pages");
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 = {
  "parent": {
    "type": "page_id",
    "page_id": "11111111-1111-4111-8111-111111111111"
  },
  "properties": {
    "title": {
      "type": "title",
      "title": [
        {
          "type": "text",
          "text": {
            "content": "API 接入测试"
          }
        }
      ]
    }
  },
  "children": [
    {
      "object": "block",
      "type": "paragraph",
      "paragraph": {
        "rich_text": [
          {
            "type": "text",
            "text": {
              "content": "这是一条通过 API 保存的测试记录。"
            }
          }
        ]
      }
    }
  ]
};
const response = await fetch(url, {
  method: "POST",
  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 为新页面 ID，url 用于打开页面。以下为结构示意，非本站实测结果。

{
  "object": "page",
  "id": "22222222-2222-4222-8222-222222222222",
  "url": "https://www.notion.so/22222222222242228222222222222222",
  "parent": {
    "type": "page_id",
    "page_id": "11111111-1111-4111-8111-111111111111"
  },
  "properties": {
    "title": {
      "type": "title",
      "title": [
        {
          "type": "text",
          "text": {
            "content": "API 接入测试"
          },
          "plain_text": "API 接入测试"
        }
      ]
    }
  }
}

常见错误与排查

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

调用注意

向 data_source 新建条目时应改 parent.data_source_id，properties 必须匹配该数据源 schema，不能直接照搬普通页面写法。
没有幂等键的创建请求超时后先查找实际结果，避免无条件重试生成重复页面。

Create a page

注意事项

本例使用公开稳定的内容块结构；Secret 只存服务端。

核验来源

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

01
Create your first connection核验日期 2026-10-15
02
API versioning核验日期 2026-10-15
03
Create a page核验日期 2026-10-15

Notion 数据 API的其他调用手册

读取页面正文并追加段落定位数据源并查询数据库条目

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