wolai API 参考文档

API 概述

wolai API 是基于 REST 的接口，用于操作 wolai 工作空间中的页面和数据库。

认证

所有 API 请求都需要在请求头中包含认证信息：

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

基础 URL

https://api.wolai.com/v1

核心操作

1. 创建页面

端点: POST /databases

请求体:```json
{
"parent_id": "父页面ID",
"title": "页面标题",
"type": "page",
"content": [内容块数组]
}

```json
{
  "id": "页面ID",
  "title": "页面标题",
  "type": "page",
  "content": [内容块数组],
  "created_time": "2023-01-01T00:00:00.000Z"
}

2. 更新页面内容

端点: PATCH /databases/{page_id}

请求体:

{
  "content": [新的内容块数组]
}

注意: 这是覆盖式更新，需要先获取现有内容，合并后再提交。

3. 获取页面详情

端点: GET /databases/{page_id}

响应: 返回页面的完整信息，包括 content 数组。

4. 搜索页面

端点: POST /search

请求体:```json
{
"query": "搜索关键词",
"type": "database"
}

```json
{
  "results": [
    {
      "id": "页面ID",
      "title": "页面标题",
      "type": "page"
    }
  ]
}

内容块格式

wolai 使用块（block）系统组织内容。每个块是一个 JSON 对象：

文本块

{
  "type": "text",
  "content": "普通文本内容"
}

标题块

{
  "type": "heading_1",  // heading_1, heading_2, heading_3
  "content": "标题文本"
}

列表块

{
  "type": "bulleted_list",  // bulleted_list, numbered_list, todo_list
  "content": ["项目1", "项目2", "项目3"]
}

代码块

{
  "type": "code",
  "language": "python",  // 可选：python, javascript, json 等
  "content": "代码内容"
}

引用块

{
  "type": "quote",
  "content": "引用文本"
}

使用 Python 脚本

wolai_api.py

提供了 WolaiClient 类封装核心 API 操作。

初始化:

from wolai_api import WolaiClient

client = WolaiClient("your-api-token")

创建页面:

result = client.create_page(
    parent_id="parent-page-id",
    title="新页面标题",
    content_blocks=[...]
)

更新页面:

result = client.update_page_content(
    page_id="page-id",
    content_blocks=[...]
)

获取页面:

page = client.get_page("page-id")

搜索页面:

results = client.search_pages("关键词")

sync_conversation.py

用于同步对话内容到 wolai 页面。

同步到现有页面:

python3 sync_conversation.py \\
  --token YOUR_TOKEN \\
  --page-id PAGE_ID \\
  --conversation-file conversation.json

创建新页面:

python3 sync_conversation.py \\
  --token YOUR_TOKEN \\
  --parent-id PARENT_ID \\
  --title "对话记录" \\
  --conversation-file conversation.json

conversation.json 格式:

{
  "user": {
    "name": "用户名",
    "id": "user-id"
  },
  "messages": [
    {
      "role": "user",
      "content": "用户消息"
    },
    {
      "role": "assistant",
      "content": "助手回复"
    }
  ],
  "tags": ["标签1", "标签2"]
}

错误处理

API 可能返回以下 HTTP 状态码：

200: 成功
400: 请求参数错误
401: 认证失败（token 无效）
403: 权限不足
404: 页面不存在
429: 请求过于频繁
500: 服务器错误

错误响应格式：

{
  "error": {
    "code": "错误代码",
    "message": "错误描述"
  }
}

最佳实践

API Token 安全: 不要将 token 硬编码在代码中，使用环境变量或配置文件
错误重试: 对 429、500 等错误实现指数退避重试
内容合并: 更新页面时先获取现有内容，合并后再提交避免数据丢失
批量操作: 大量内容块建议分批次同步，单次不超过 100 个块
缓存: 频繁访问的页面数据可以缓存，减少 API 调用

获取 API Token

登录 wolai 网页版
进入「设置」→「开发者」
生成 API Token
妥善保管，不要泄露给他人

参考资料

🚀 增强版 API 客户端（New）

我们提供了增强版 API 客户端 (wolai_api_enhanced.py)，相比基础版本有以下改进：

新增功能

自动重试机制
- 可配置重试次数（默认 3 次）
- 指数退避延迟
- 自动处理 429（速率限制）和 5xx（服务器错误）
增强的 Block 类型支持
- 代码块：create_code_block(code, language="python"))
- 引用块：create_quote_block(text)
- 提示框：create_callout_block(text, icon="💡")
- 分隔线：create_separator()
- 列表：无序列表和有序列表
批量处理工具
- batch_create_blocks(blocks, batch_size=20) - 分批处理
- validate_block(block) - 验证 block 格式
改进的错误处理
- 详细的错误信息和调试日志
- HTTP 状态码特定处理
- 响应内容解析和显示

使用增强版

from wolai_api_enhanced import WolaiClient, create_code_block, create_callout_block

# 初始化（带重试）
client = WolaiClient("your-token", max_retries=3)

# 创建代码块示例
blocks = [
    create_callout_block("这是重要提示", icon="⚠️"),
    create_code_block('print("Hello World")', language="python")
]

# 创建页面
result = client.create_page(
    parent_id="parent-id",
    title="带代码的页面",
    content_blocks=blocks
)

增强版脚本

sync_conversation_enhanced.py: 增强版同步脚本，支持三种格式（detailed/compact/minimal）
推荐使用增强版进行新开发，获得更好的错误处理和内容格式支持

提示: 增强版完全兼容现有接口，可直接替换使用以获得更好的稳定性和功能。

📄 api_guide.md