果子集 OpenAPI 外部发布文章接口文档

为了方便第三方平台（如 OpenClaw、自动化写作脚本等）向“果子集”网站直接推送并发布文章，系统提供了专属的 OpenAPI 接口。

1. 前置准备：配置鉴权 Key

在调用接口之前，您必须在果子集网站的后台管理系统中配置好鉴权密钥：

登录管理员账号，进入 后台管理 -> 站点配置。
找到 外部 API (OpenAPI) 鉴权配置 区域。
在 OpenAPI Key 输入框中，设置一个随机且复杂的字符串。
- 格式要求：建议使用包含大小写字母和数字的组合，避免使用特殊符号。
- 位数建议：建议长度在 32位到64位 之间，以保证足够的安全性（例如：sk1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p）。
点击保存。

请求头鉴权格式：

所有 OpenAPI 请求必须在 Header 中携带 Authorization，格式为 Bearer <您的 OpenAPI Key>。

2. 接口列表

GET

2.1 查询所有可用知识空间 (Spaces)

请求路径： /api/openapi/spaces

完整URL示例： https://你的域名/api/openapi/spaces

Content-Type： application/json

说明： 返回所有在前台设为可见 (is_visible: true) 的知识空间列表，主要用于获取 space_id 以便在发布文章时使用。

响应示例：

{
  "success": true,
  "message": "Spaces fetched successfully",
  "data": [
    {
      "space_id": "7307678792883945476",
      "name": "果子悟了与Z思维",
      "description": "内容简介...",
      "is_free": true
    }
  ]
}

POST

2.2 发布新文章

请求路径： /api/openapi/article/publish

完整URL示例： https://你的域名/api/openapi/article/publish

Content-Type： application/json

请求体参数 (Body)：

参数名	类型	必填	说明
title	String	是	文章标题
content	String	是	文章正文（支持 HTML 格式或纯文本）
space_id	String	是	目标知识空间的 ID（可前往后台“知识空间管理”列表中查看 ID）
parent_node_token	String	否	目标父节点的 ID。如果传空或不传，则默认发布在该空间的根目录下。如果要挂在某个文件夹或文章下，传入其对应的节点 ID。
is_published	Boolean	否	是否立即在前台公开展示。默认 `true`
is_free	Boolean	否	是否为免费文章。默认 `true`

POST

2.3 修改/更新现有文章

请求路径： /api/openapi/article/update

完整URL示例： https://你的域名/api/openapi/article/update

Content-Type： application/json

请求体参数 (Body)：

参数名	类型	必填	说明
node_token	String	是	要修改的目标文章节点 ID（可以在后台“节点与内容管理”中复制 ID）
title	String	否	修改后的文章标题。不传则保持原样
content	String	否	修改后的文章正文（支持 HTML 格式或纯文本）。不传则保持原样
is_published	Boolean	否	是否公开展示
is_free	Boolean	否	是否免费

注：title, content, is_published, is_free 至少需要提供其中一个参数进行更新。

3. 请求示例

示例 1：使用 cURL (Bash)

curl -X POST http://localhost:3000/api/openapi/article/publish \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-mysupersecretkey2026" \
  -d '{
    "title": "OpenClaw 自动发布的 AI 资讯",
    "content": "<h1>今日 AI 动态</h1><p>这是一篇通过外部 API 自动推送到果子集网站的测试文章。</p>",
    "space_id": "7307678792883945476",
    "is_published": true,
    "is_free": true
  }'

示例 2：使用 Python (requests)

import requests

url = "https://你的域名/api/openapi/article/publish"
headers = {
    "Authorization": "Bearer sk-mysupersecretkey2026",
    "Content-Type": "application/json"
}
payload = {
    "title": "Python 脚本发布测试",
    "content": "<p>这是正文内容，支持 <strong>加粗</strong> 等 HTML 标签。</p>",
    "space_id": "7307678792883945476",
    "parent_node_token": "" # 选填
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

4. 响应说明

成功响应 (HTTP Status 201)

发布成功后，接口会返回新文章在系统内部生成的唯一节点 ID 和前台访问的 URL。

{
  "success": true,
  "message": "Article published successfully",
  "data": {
    "node_token": "ext_node_1711867200000_abc123",
    "obj_token": "ext_obj_1711867200000_abc123",
    "url": "/space/7307678792883945476/doc/ext_node_1711867200000_abc123"
  }
}

常见错误响应

鉴权失败 (HTTP Status 401 / 403)

{
  "error": "Invalid API Key or OpenAPI feature is not configured"
}

缺少必填参数 (HTTP Status 400)

{
  "error": "Missing required fields: title, content, space_id"
}

目标空间或父节点不存在 (HTTP Status 404)

{
  "error": "Space with space_id 'xxxx' does not exist"
}