2Ryun REST API 技术说明书

更新：12小时前

版本：1.0 | 最后更新：2026-08-01 | 最后验证：2026-08-01（44 端点全部测试通过）

概述

获取 API Key登录 2Ryun → 设置 → API Keys → 创建新 Key。Key 格式为 sk- 前缀 + 多段随机字符串。使用时放在 Authorization: Bearer <key> Header 中。内容访问 URL 规则以下 URL 用于向用户展示已发布的内容，无需 API Key，可直接在浏览器打开。

API → URL 映射：

POST /generate → generation_id → 发布后: restapi/genhtml/public/GEN_ID
POST /sites → site_id → 发布后: /s/SITE_ID
POST /documents/create → document（即 _id） → 文档页: /app/DOC_ID

预览（未发布）：GET /restapi/gen-html/generations/:id/html 返回 JSON { "html": "..." }，可自行渲染。

1. 文档管理 (Documents)1.1 文档列表GET /restapi/documents列出当前用户的所有文档，支持分页和筛选。查询参数

返回{ "documents": [ { "_id": "6a69810fef276a17f2fb089f", "title": "产品白皮书", "content": "# 产品概述\n\n这是产品白皮书的正文内容...", "summary": "产品概述简介", "tags": ["产品", "技术"], "board": "", "parentId": "6a69810fef276a17f2fb089e", "rootId": "6a69810fef276a17f2fb089e", "createdBy": "6a66b4a939b7b51cc8dc3b16", "createdAt": "2026-07-29T03:00:00.000Z", "updatedAt": "2026-07-29T03:00:00.000Z" } ], "total": 42 }

1.2 获取单个文档GET /restapi/documents/:id路径参数

返回：单个文档完整对象（字段同 1.1 documents 数组元素），包含 content 正文。

1.3 搜索文档GET /restapi/documents/search查询参数

返回：格式同 1.1，返回匹配的文档列表。

1.4 创建文档POST /restapi/documents/create请求体 (JSON)

请求示例curl -X POST https://www.2ryun.com/restapi/documents/create \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "新文档", "content": "# 第一章\n\n正文内容...", "tags": ["技术", "AI"], "parentId": "6a69810fef276a17f2fb089e", "rootId": "6a69810fef276a17f2fb089e", "setting": {"autoExtractWiki": true} }'返回{ "message": "Document created successfully", "document": "6a69810fef276a17f2fb089f" }

1.5 导入文件POST /restapi/documents/import上传文件并自动转换为 Markdown。支持 pdf、docx、xlsx、pptx、md、markdown、txt、html、htm、csv。请求格式：multipart/form-data

请求示例curl -X POST https://www.2ryun.com/restapi/documents/import \ -H "Authorization: Bearer $API_KEY" \ -F "file=@report.pdf" \ -F "title=季度报告" \ -F "parentId=6a69810fef276a17f2fb089e"返回：同 1.4 创建文档的返回格式。文档已自动创建，content 为转换后的 Markdown。

1.6 更新文档PUT /restapi/documents/update/:id路径参数：id — 文档 ID请求体 (JSON)：所有字段均为可选，只传需要更新的字段。

请求示例curl -X PUT https://www.2ryun.com/restapi/documents/update/6a69810fef276a17f2fb089f \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"title": "更新后的标题", "content": "更新后的内容", "tags": ["新标签"]}'返回：更新后的完整文档对象（格式同 1.1 返回的 documents 数组元素）。

1.7 删除文档DELETE /restapi/documents/delete/:id返回{ "message": "Document deleted successfully" }

1.8 批量获取文档POST /restapi/documents/batch一次请求获取多篇文档的完整内容。适合批量操作场景。请求体 (JSON)

请求示例curl -X POST https://www.2ryun.com/restapi/documents/batch \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"ids": ["6a69810fef276a17f2fb089f", "6a69810fef276a17f2fb08a0"]}'返回[ { "_id": "6a69810fef276a17f2fb089f", "title": "文档一", "content": "# 文档一\n\n正文...", "tags": ["tag1"], "createdAt": "2026-07-29T03:00:00.000Z" }, { "_id": "6a69810fef276a17f2fb08a0", "title": "文档二", "content": "# 文档二\n\n正文...", "tags": ["tag2"], "createdAt": "2026-07-29T04:00:00.000Z" } ]返回文档数组，每个元素格式同 1.1。

1.9 复制文档POST /restapi/documents/duplicate/:id复制指定文档及其内容。新文档标题为原标题 + " (Copy)"。

1.10 获取文档树GET /restapi/documents/fulltree/:rootId获取以 :rootId 为根的完整文档树结构，返回嵌套的子文档数组。返回{ "_id": "rootId", "title": "根文档", "children": [ { "_id": "child1", "title": "子文档1", "children": [] } ] }

1.11 公开文档GET /restapi/documents/public/:id访问设置为公开的文档。无需 API Key。1.12 文档概要GET /restapi/documents/simple/:id获取文档基本信息（不含完整 content）。无需文档所有权检查。1.13 获取文档（别名）GET /restapi/documents/get/:id同 1.2，获取完整文档内容。使用 checkDocumentAccess 中间件（不强制 API Key 认证，但检查访问权限）。1.14 分享文档POST /restapi/documents/share/:id将文档分享给指定用户。请求体 (JSON)

1.15 更新分享权限PUT /restapi/documents/sharing/:id更新已分享文档的访问权限设置。1.16 获取分享记录GET /restapi/documents/shares/:id返回该文档的所有分享记录列表。1.17 取消分享DELETE /restapi/documents/share/:id/:userId取消对特定用户的文档分享。1.18 分享文档树POST /restapi/documents/tree/sharing/:id将整个文档树分享出去。1.19 更新文档树POST /restapi/documents/tree/:id请求体 (JSON)：{ "tree": [...] } — 新的树结构数据。

2. 知识库 (Wiki)2.1 知识提取POST /restapi/wiki/extract调用 AI 从文档正文中提取结构化知识条目。同步操作，耗时 1-3 分钟。请求体 (JSON)

请求示例curl -X POST https://www.2ryun.com/restapi/wiki/extract \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "content": "# 人工智能概述\n\n人工智能（Artificial Intelligence，简称 AI）是计算机科学的一个重要分支...", "title": "AI Overview", "content_id": "6a69810fef276a17f2fb089f", "tags": ["AI", "技术"] }'成功返回 (200){ "entries_created": 3, "entries": [ { "id": "6a69810fef276a17f2fb0900", "title": "人工智能", "content": "人工智能（Artificial Intelligence，简称 AI）是计算机科学的一个重要分支，旨在创建能够执行通常需要人类智能的任务的系统。", "summary": "人工智能是计算机科学中研究智能系统的分支", "category": "concept", "confidence_score": 0.95, "confidence_tier": "extracted", "tags": ["AI", "技术", "计算机科学"], "relations": [ { "related_entry": "6a69810fef276a17f2fb0901", "label": "核心技术" } ], "enrichments": [ { "type": "background_context", "content": "AI 的概念最早由 John McCarthy 在 1956 年提出", "target_text": "人工智能", "confidence": 0.9 } ], "sources": [ { "type": "document", "name": "AI Overview", "content_id": "6a69810fef276a17f2fb089f" } ] }, { "id": "6a69810fef276a17f2fb0901", "title": "机器学习", "content": "机器学习是人工智能的子领域，专注于从数据中学习的算法...", "summary": "机器学习是 AI 中从数据学习的子领域", "category": "concept", "confidence_score": 0.92, "confidence_tier": "extracted", "tags": ["AI", "机器学习", "算法"], "relations": [], "enrichments": [], "sources": [{"type": "document", "name": "AI Overview", "content_id": "6a69810fef276a17f2fb089f"}] } ] }

enrichments 子字段

2.2 批量提取POST /restapi/wiki/extract-batch一次提取多篇文档。自动跳过已提取的文档（当 skip_if_extracted=true）。请求体 (JSON)

请求示例curl -X POST https://www.2ryun.com/restapi/wiki/extract-batch \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "docs": [ {"content": "# 文档一\n正文...", "content_id": "id1", "title": "文档一"}, {"content": "# 文档二\n正文...", "content_id": "id2", "title": "文档二"} ], "skip_if_extracted": true }'返回{ "results": [ {"docId": "id1", "created": 5}, {"docId": "id2", "created": 0} ], "errors": [ {"docId": "id3", "error": "content too short"} ], "total": 2, "extracted": 1, "skipped": 1 }

2.3 整理知识POST /restapi/wiki/organize对用户的知识库执行去重、聚类、关联发现。同步操作，耗时 1-5 分钟。 建议在批量提取后执行一次。无请求体（参数从 API Key 推断用户身份）。请求示例curl -X POST https://www.2ryun.com/restapi/wiki/organize \ -H "Authorization: Bearer $API_KEY"返回{ "merged": 3, "linked": 15, "new_clusters": 4, "stale_flagged": 1, "insights": [ { "insight": "「人工智能」「机器学习」「深度学习」三个条目形成紧密的知识群，覆盖了从基础到应用递进的层次结构", "supporting_entries": [ {"id": "6a69...01", "title": "人工智能"}, {"id": "6a69...02", "title": "机器学习"}, {"id": "6a69...03", "title": "深度学习"} ] }, { "insight": "产品相关的 5 篇文档中反复出现「用户体验」主题，建议创建专题页面汇总", "supporting_entries": [ {"id": "6a69...04", "title": "产品设计原则"}, {"id": "6a69...05", "title": "用户调研报告"} ] } ] }

2.4 条目列表GET /restapi/wiki/entries查询参数

返回{ "entries": [ { "id":"...", "title":"...", "summary":"...", "category":"...", "status":"active" } ], "total": 128 }

2.5 获取单条知识GET /restapi/wiki/entries/:id返回完整的条目对象（格式同 2.1 返回的 entries 数组元素）。

2.6 创建条目POST /restapi/wiki/entries手动创建知识条目。请求体 (JSON)

2.7 更新条目PUT /restapi/wiki/entries/:id请求体：同 2.6，所有字段可选。

2.8 删除条目DELETE /restapi/wiki/entries/:id2.9 审核 EnrichmentPATCH /restapi/wiki/entries/:entryId/enrichments/:enrichmentIdAI 提取知识时会生成 enrichment（背景知识补充/修正建议）。通过此接口接受或拒绝。请求体 (JSON)

2.10 知识搜索GET /restapi/wiki/search通过语义搜索（向量 + 关键词混合）查找相关知识条目。查询参数

请求示例curl "https://www.2ryun.com/restapi/wiki/search?q=人工智能&max_results=5" \ -H "Authorization: Bearer $API_KEY"返回[ { "id": "6a69810fef276a17f2fb0900", "title": "人工智能", "summary": "人工智能是计算机科学中研究智能系统的分支", "content": "人工智能（AI）是...", "category": "concept", "confidence_score": 0.95, "tags": ["AI", "技术"], "score": 0.987, "match_type": "semantic" } ]

2.11 语义链接POST /restapi/wiki/semantic-link自动计算条目间的语义相似度并创建链接。请求体 (JSON)

返回{ "links_created": 42 }

2.12 知识图谱GET /restapi/wiki/graph GET /restapi/wiki/graph/data/graph 返回可视化用的简化结构（节点+边）。

/graph/data 返回带元数据的完整图谱数据。查询参数：root_id（可选，限定范围）、max_nodes（可选，默认 200）

2.13 提取状态GET /restapi/wiki/extracted-status查询哪些文档已经被提取过。查询参数：content_ids — 逗号分隔的文档 ID 列表请求示例curl "https://www.2ryun.com/restapi/wiki/extracted-status?content_ids=id1,id2,id3,id4" \ -H "Authorization: Bearer $API_KEY"返回{ "extracted": ["id1", "id3"], "not_extracted": ["id2", "id4"] }

2.14 知识库统计GET /restapi/wiki/stats返回用户的条目总数、各分类分布、各状态计数等汇总数据。返回{ "total_entries": 256, "by_category": {"concept": 120, "person": 30, "technology": 45}, "by_status": {"active": 230, "disabled": 26}, "by_confidence": {"extracted": 180, "inferred": 60, "ambiguous": 16}, "total_links": 512, "total_clusters": 28 }

2.15 操作日志GET /restapi/wiki/operation-log查询参数：limit（默认 50）、entry_id（可选，筛选特定条目）返回：操作记录数组，每条包含操作类型、时间、详情。

3. 网页生成 (Gen-HTML)3.1 生成网页POST /restapi/gen-html/generate将 Markdown 文档转换为完整的 HTML 网页。同步操作，耗时 30-120 秒。请求体 (JSON)

可用模板：可通过 GET /restapi/gen-html/templates 获取完整列表。常用：

article-magazine — 文章/博客类
documentation — 技术文档
landing-page — 产品落地页
magazine-minimal — 极简站点

请求示例curl -X POST https://www.2ryun.com/restapi/gen-html/generate \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "content": "# Hello World\n\n这是我的第一篇 AI 生成网页。", "title": "My First Page", "template": "article-magazine" }'返回{ "generation_id": "6a69810fef276a17f2fb0900", "template": "article-magazine", "title": "My First Page", "size": 12580, "created_at": "2026-07-29T03:00:00.000Z" }

3.2 模板列表GET /restapi/gen-html/templates返回{ "templates": [ {"name": "article-magazine", "label": "杂志文章", "description": "Substack / Medium 高级感长文排版", "category": "article", "has_example": true}, {"name": "documentation", "label": "技术文档页", "description": "三栏文档页: 侧导航 + 正文 + 右 TOC", "category": "doc", "has_example": true}, {"name": "landing-page", "label": "SaaS Landing", "description": "单页落地页", "category": "prototype", "has_example": true}, {"name": "magazine-minimal", "label": "杂志风海报", "description": "极简杂志站点", "category": "poster", "has_example": true} ], "user_templates": [] }

3.3 模板预览GET /restapi/gen-html/templates/:name/example返回该模板的示例 HTML（无需 API Key）。

3.4 生成记录列表GET /restapi/gen-html/generations查询参数

返回{ "generations": [ { "generation_id": "6a69810fef276a17f2fb0900", "title": "My First Page", "template": "article-magazine", "content_id": "6a69810fef276a17f2fb089f", "size": 12580, "visibility": "private", "created_at": "2026-07-29T03:00:00.000Z" } ], "total": 15 }

3.5 获取生成记录详情GET /restapi/gen-html/generations/:id返回单条记录元信息（不含 HTML，格式同 3.4 的数组元素）。

3.6 获取生成的 HTMLGET /restapi/gen-html/generations/:id/html返回{ "html": "<!DOCTYPE html>\n<html>...完整的 HTML 页面...</html>" }

3.7 编辑 HTMLPUT /restapi/gen-html/generations/:id/html请求体 (JSON)

3.8 删除生成记录DELETE /restapi/gen-html/generations/:id

3.9 AI 对话编辑POST /restapi/gen-html/generations/:id/chat通过自然语言指令修改网页（如"把标题改为红色"）。请求体 (JSON)

请求示例curl -X POST https://www.2ryun.com/restapi/gen-html/generations/xxx/chat \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"feedback": "请把页面标题颜色改为深蓝色，字号增大到 32px"}'返回：更新后的 { generation_id, template, size } 同 3.1。

3.10 发布 / 取消发布POST /restapi/gen-html/generations/:id/publish POST /restapi/gen-html/generations/:id/unpublish发布后获得公开 URL。无需 API Key 即可通过 GET /restapi/gen-html/public/:generation_id 访问。返回{ "message": "published", "generation_id": "xxx" }

3.11 保存封面PATCH /restapi/gen-html/generations/:id/cover请求体 (JSON)

3.12 创建站点POST /restapi/gen-html/sites将一个文档树创建为多页面网站。请求体 (JSON)

请求示例curl -X POST https://www.2ryun.com/restapi/gen-html/sites \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "我的知识库", "content_id": "6a69810fef276a17f2fb089f", "template": "magazine-minimal", "docs": [ {"content_id": "id1", "title": "首页", "content": "# 欢迎\n这是首页", "parent_id": null}, {"content_id": "id2", "title": "产品", "content": "# 产品\n产品介绍", "parent_id": "id1"}, {"content_id": "id3", "title": "关于", "content": "# 关于\n关于我们", "parent_id": null} ] }'返回{ "site_id": "6a69810fef276a17f2fb0900", "name": "我的知识库", "pages": [ {"slug": "", "title": "首页", "content_id": "id1"}, {"slug": "product", "title": "产品", "content_id": "id2", "parent_slug": ""}, {"slug": "about", "title": "关于", "content_id": "id3"} ], "template": "magazine-minimal" }

3.13 站点列表GET /restapi/gen-html/sites返回{ "sites": [ { "site_id": "6a69810fef276a17f2fb0900", "name": "我的知识库", "root_id": "6a69810fef276a17f2fb089f", "template": "magazine-minimal", "pages_count": 5, "created_at": "2026-07-29T03:00:00.000Z" } ] }

3.14 站点详情GET /restapi/gen-html/sites/:id返回完整的站点对象，含 pages 数组（格式同 3.12 返回）。

3.15 删除站点DELETE /restapi/gen-html/sites/:id可选请求体 { "delete_pages": true } 同时删除关联的生成页面。

3.16 重生成站点页面PUT /restapi/gen-html/sites/:site_id/regenerate-page/:slug重新生成站点中的某个页面。路径参数：site_id — 站点 ID，slug — 页面标识请求体 (JSON)

3.17 发布 / 取消发布站点POST /restapi/gen-html/sites/:id/publish POST /restapi/gen-html/sites/:id/unpublish发布后站点可通过 https://2ryun.com/s/SITE_ID 访问。

3.18 批量生成页面POST /restapi/gen-html/sites/:id/pages/batch为站点批量生成多个页面。请求体 (JSON)

3.19 公开访问（无需 API Key）GET /restapi/gen-html/public/:generation_id返回已发布的 HTML 页面。可直接在浏览器中打开。

4. 用户信息 (Users)4.1 查询积分和配额GET /restapi/users/quota返回当前用户的积分、存储、文件、站点配额及使用情况。请求示例curl "https://www.2ryun.com/restapi/users/quota" \ -H "Authorization: Bearer $API_KEY"返回{ "plan": "pro", "credits": { "current": 1850, "limit": 2000, "low": false, "expired": false, "expires_at": "2026-08-28T00:00:00.000Z", "days_left": 27 }, "storage": { "used": 5242880, "limit": 1073741824, "usage_percent": 0 }, "files": { "used": 15, "limit": 1000 }, "sites": { "used": 2, "limit": 10 }, "tokens": { "used": 450000, "limit": 100000 } }

通用错误码

积分不足（402）处理涉及 AI 调用的接口在用户积分不足时会返回 402。Agent 应正确处理此错误。涉及的接口：wiki/extract、wiki/extract-batch、wiki/organize、genhtml/generate、genhtml/sites（创建站点时会调 AI）。402 错误响应：{ "error": "积分不足，请充值" }Agent 收到 402 时应：

告知用户积分已用完，引导到 /pricing 页面充值

不要重试（积分不会自动恢复）

已完成的非 AI 操作（如文档创建）仍然有效