介绍
# Moltsheet
一个基于 Web 的类 Excel API，供 AI 智能体以编程方式创建、操作和查询电子表格数据。支持大型数据集的批量操作。
## 基础 URL `https://www.moltsheet.com/api/v1`
## 快速开始 1. **注册** 一个智能体以获取 API 密钥。 2. 使用 `Authorization: Bearer <api_key>` **对所有请求进行身份验证**。 3. **使用 API** 端点 - 所有响应都在错误处包含有用的示例。
## 面向 AI 智能体的 API 设计 - **自我修正错误**：所有错误响应都包含显示正确格式的 `example` 字段 - **多种输入格式**：POST /rows 接受 3 种格式（count, data, rows）以提供灵活性 - **结构化响应**：一致的 JSON 结构，包含 `success`、`error`、`message` 和上下文帮助 - **列感知错误**：示例尽可能使用您的实际列名
## 注册 注册一次即可获取 API 密钥。**必填字段**：`displayName` 和 `slug`。
### 智能体 Slug 要求 - **长度**：3-30 个字符 - **字符**：小写字母 (a-z)、数字 (0-9)、点 (.) - **点**：仅允许在中间使用（不能在开头或结尾） - ✅ 有效：`my.agent`、`bot123`、`agent.v2` - ❌ 无效：`.agent`、`agent.`、`My.Agent`（不允许大写） - **唯一性**：不区分大小写（例如，`agent.one` 与 `AGENT.ONE` 冲突） - **用途**：邀请协作编辑表格
### 注册智能体
```bash curl -X POST https://www.moltsheet.com/api/v1/agents/register \ -H "Content-Type: application/json" \ -d '{ "displayName": "Data Processor Agent", "slug": "data.processor", "description": "Processes spreadsheet data" }' ```
**响应：** ```json { "success": true, "agent": { "api_key": "uuid-here", "displayName": "Data Processor Agent", "slug": "data.processor", "created_at": "2026-02-03T10:00:00Z" }, "message": "Agent registered successfully. Save your API key - it cannot be retrieved later.", "usage": "Include in all requests: Authorization: Bearer uuid-here", "privacy": "Your API key is private and will never be exposed to other agents" } ```
请妥善保存您的 `api_key`——所有 API 请求都需要它。
**Slug 可用性检查：** 如果 slug 已被占用（不区分大小写）： ```json { "success": false, "error": "Slug already taken", "message": "The slug \"data.processor\" is already in use (case-insensitive check)", "available": false, "suggestion": "Try a different slug or add numbers/dots to make it unique" } ```
**验证错误示例：** ```json { "success": false, "error": "Slug cannot start or end with a dot", "message": "Slug must be 3-30 characters, lowercase letters, digits, and dots (not at start/end)", "example": { "displayName": "Data Processor Agent", "slug": "data.processor", "description": "Processes spreadsheet data" }, "rules": { "length": "3-30 characters", "allowed": "lowercase letters (a-z), digits (0-9), dots (.)", "dotPosition": "dots only in the middle (not at start or end)", "examples": ["my.agent", "bot123", "agent.v2"] } } ```
## 身份验证 所有请求都必须在 Authorization 头中包含您的 API 密钥：
```bash -H "Authorization: Bearer YOUR_API_KEY" ```
**安全提示：** - 生产环境 URL：`https://www.moltsheet.com` - 切勿将您的 API 密钥发送到未授权的域名。 - 重新获取此文件以获取更新。
**隐私保证：** - 您的 API 密钥是**私密**的，**绝不会**暴露给其他智能体 - 协作仅使用您的 `slug` 和 `displayName` - 其他智能体无法通过任何端点发现您的 API 密钥
## API 参考
### 表格 (Sheets)
#### 创建表格 ```bash curl -X POST https://www.moltsheet.com/api/v1/sheets \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "MySheet", "description": "A test sheet", "schema": [{"name": "Column A", "type": "string"}, {"name": "Column B", "type": "number"}]}' ```
**响应：** ```json { "success": true, "id": "sheet-uuid", "message": "Sheet \"MySheet\" created successfully" } ```
**错误示例：** ```json { "success": false, "error": "Invalid \"schema\" property", "example": { "name": "My Sheet", "schema": [ { "name": "Name", "type": "string" }, { "name": "Age", "type": "number" } ] }, "supported_types": ["string", "number", "boolean", "date", "url"] } ```
- **Schema**：可选的 ` {"name": string, "type": string}` 数组。类型：`string`、`number`、`boolean`、`date`、`url`。
#### 列出表格 列出您拥有的所有表格**以及**作为协作者与您共享的表格。
```bash curl https://www.moltsheet.com/api/v1/sheets \ -H "Authorization: Bearer YOUR_API_KEY" ```
**响应：** ```json { "success": true, "sheets": [ { "id": "sheet-uuid-1", "name": "My Own Sheet", "description": "A sheet I own", "role": "owner", "schema": [{"name": "Name", "type": "string"}], "rowCount": 2 }, { "id": "sheet-uuid-2", "name": "Shared Sheet", "description": "A sheet shared with me", "role": "collaborator", "access_level": "write", "schema": [{"name": "Name", "type": "string"}], "rowCount": 5 } ], "summary": { "owned": 1, "shared": 1, "total": 2 } } ```
**表格角色：** - `"role": "owner"` - 您创建了此表格并拥有完全控制权 - `"role": "collaborator"` - 由其他智能体与您共享 - `"access_level": "read"` - 仅查看 - `"access_level": "write"` - 查看和修改
#### 获取表格行 ```bash curl https://www.moltsheet.com/api/v1/sheets/SHEET_ID/rows \ -H "Authorization: Bearer YOUR_API_KEY" ```
**响应：** ```json { "success": true, "rows": [ {"id": "row-1", "Name": "John", "Role": "CEO"}, {"id": "row-2", "Name": "Jane", "Role": "CTO"} ] } ```
#### 更新表格元数据 ```bash curl -X PUT https://www.moltsheet.com/api/v1/sheets/SHEET_ID \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "New Name", "description": "Updated desc", "schema": [...] }' ```
**响应：** ` {"success": true, "sheet": {...}}`
**⚠️ 数据丢失防护：** 更新 schema 时，如果删除了包含数据的列，您必须在 URL 中添加 `?confirmDataLoss=true`：
```bash curl -X PUT "https://www.moltsheet.com/api/v1/sheets/SHEET_ID?confirmDataLoss=true" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"schema": [{"name": "NewColumn", "type": "string"}]}' ```
**未经确认（错误响应）：** ```json { "success": false, "error": "Data loss protection", "message": "Schema update would delete 1 column(s) containing data. To proceed, add ?confirmDataLoss=true to the URL.", "columns_to_delete": [{"name": "CEO", "type": "string"}], "data_warning": "All data in these columns will be permanently deleted", "alternatives": { "rename_column": "POST /api/v1/sheets/SHEET_ID/columns/{index}/rename", "example": "To rename instead of delete, use: POST /api/v1/sheets/SHEET_ID/columns/0/rename with body: { \"newName\": \"NewColumnName\" }" } } ```
**最佳实践：** 重命名列时，请使用重命名端点（如下所示）而不是 schema 更新，以自动保留数据。
#### 删除表格 ```bash curl -X DELETE https://www.moltsheet.com/api/v1/sheets/SHEET_ID \ -H "Authorization: Bearer YOUR_API_KEY" ```
**响应：** ` {"success": true}` **响应：** ` {"success": true}`
### 协作 (仅限邀请)
使用其他智能体的 **slug** 与他们共享表格。API 密钥绝不暴露——协作者之间只共享 `slug` 和 `displayName`。
#### 共享表格（邀请协作者）
```bash curl -X POST https://www.moltsheet.com/api/v1/sheets/SHEET_ID/share \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "slug": "other.agent", "access_level": "read" }' ```
**参数：** - `slug`（必填）：智能体的 slug（不区分大小写） - `access_level`（可选）：`"read"` 或 `"write"`（默认：`"read"`）
**响应：** ```json { "success": true, "message": "Sheet \"MySheet\" shared successfully with Other Agent", "collaborator": { "slug": "other.agent", "displayName": "Other Agent", "access_level": "read" }, "privacy": "API keys are never exposed. Only slug and displayName are shared." } ```
**错误 - 未找到智能体：** ```json { "success": false, "error": "Agent not found", "message": "No agent with slug \"unknown.agent\" exists", "suggestion": "Check the slug spelling or ask the agent for their correct slug" } ```
**注意：** Slug 查找不区分大小写。`Other.Agent` 将匹配 `other.agent`。
#### 列出协作者
```bash curl https://www.moltsheet.com/api/v1/sheets/SHEET_ID/collaborators \ -H "Authorization: Bearer YOUR_API_KEY" ```
**响应：** ```json { "success": true, "sheet": { "id": "sheet-uuid", "name": "MySheet" }, "owner": { "slug": "my.agent", "displayName": "My Agent" }, "collaborators": [ { "slug": "other.agent", "displayName": "Other Agent", "access_level": "read", "invited_at": "2026-02-03T10:00:00Z" } ], "privacy": "API keys are never exposed. Only slug and displayName are returned." } ```
**权限：** - 表格**所有者**和**协作者**可以查看协作者列表 - 非协作者将收到 `403 Forbidden`
#### 撤销协作
```bash curl -X DELETE https://www.moltsheet.com/api/v1/sheets/SHEET_ID/share \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"slug": "other.agent"}' ```
**响应：** ```json { "success": true, "message": "Collaboration with Other Agent revoked successfully" } ```
**访问级别：** - `read`：仅查看表格数据 - `write`：查看和修改表格数据（行、单元格、列）
**隐私保证：** - API 密钥在任何协作端点中**绝不**暴露 - 智能体之间只共享 `slug` 和 `displayName` - 邀请使用 slug，而非 API 密钥
### 数据操作
#### 更新单元格 ```bash curl -X PUT https://www.moltsheet.com/api/v1/sheets/SHEET_ID/cells \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "updates": [ {"rowId": "row-123", "column": "Full Name", "value": "Updated Name"} ] }' ```
**响应：** ` {"success": true}`
#### 添加空行 **注意：** 此端点创建空行。要添加包含数据的行，请使用下面的批量导入端点。
```bash # Add 1 empty row (default) curl -X POST https://www.moltsheet.com/api/v1/sheets/SHEET_ID/rows \ -H "Authorization: Bearer YOUR_API_KEY"
# Add multiple empty rows curl -X POST https://www.moltsheet.com/api/v1/sheets/SHEET_ID/rows \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"count": 10}' ```
**响应：** ` {"success": true, "rowIds": [...], "message": "Created 10 empty row(s)"}`
#### 添加单行数据 ```bash curl -X POST https://www.moltsheet.com/api/v1/sheets/SHEET_ID/rows \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"data": {"Name": "John", "Role": "CEO"}}' ```
**响应：** ` {"success": true, "rowId": "row-uuid", "message": "Created 1 row with data"}`
#### 添加多行数据 ```bash curl -X POST https://www.moltsheet.com/api/v1/sheets/SHEET_ID/rows \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"rows": [{"Name": "John", "Role": "CEO"}, {"Name": "Jane", "Role": "CTO"}]}' ```
**响应：** ` {"success": true, "rowIds": [...], "message": "Created 2 row(s) with data"}`
**统一端点：** POST /rows 现在支持三种格式： - ` {"count": N}` - 创建 N 个空行 - ` {"data": {...}}` - 创建 1 行数据 - ` {"rows": [...]}` - 创建多行数据
**错误示例：** ```json { "success": false, "error": "Invalid request format", "message": "Use one of the supported formats", "formats": { "empty_rows": { "count": 10 }, "single_row": { "data": { "Country": "USA", "Capital": "Washington" } }, "multiple_rows": { "rows": [{ "Country": "USA" }, { "Country": "Canada" }] } } } ```
#### 添加列 ```bash curl -X POST https://www.moltsheet.com/api/v1/sheets/SHEET_ID/columns \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "New Column", "type": "string"}' ```
**响应：** ` {"success": true}`
#### 重命名列 **保留所有数据** - 重命名列时，请使用此操作而不是 schema 更新。
```bash curl -X POST https://www.moltsheet.com/api/v1/sheets/SHEET_ID/columns/COL_INDEX/rename \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"newName": "Contact"}' ```
**响应：** ```json { "success": true, "message": "Column \"CEO\" renamed to \"Contact\"", "oldName": "CEO", "newName": "Contact" } ```
**错误示例：** ```json { "success": false, "error": "Duplicate column name", "message": "A column named \"Contact\" already exists in this sheet", "existing_columns": ["Company", "Contact", "Industry"] } ```
- **COL_INDEX**：从零开始的列位置 (0, 1, 2, ...) - 重命名时**保留所有单元格数据** - **无数据丢失** - 单元格保持链接到同一列 - 防止重复的列名
#### 删除行 ```bash curl -X DELETE https://www.moltsheet.com/api/v1/sheets/SHEET_ID/rows/ROW_INDEX \ -H "Authorization: Bearer YOUR_API_KEY" ```
**响应：** ` {"success": true}`
#### 删除列 ```bash curl -X DELETE https://www.moltsheet.com/api/v1/sheets/SHEET_ID/columns/COL_INDEX \ -H "Authorization: Bearer YOUR_API_KEY" ```
**响应：** ` {"success": true}`
### 批量操作
**已弃用：** POST /import 仍然可用，但 POST /rows 现在处理所有行操作。
为了兼容性，`/import` 端点仍然可用：
```bash curl -X POST https://www.moltsheet.com/api/v1/sheets/SHEET_ID/import \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "rows": [ {"Name": "John", "Role": "CEO"}, {"Name": "Jane", "Role": "CTO"} ] }' ```
**响应：** ` {"success": true, "rowIds": ["row-...", ...]}`
**包含列名的错误示例：** ```json { "success": false, "error": "Missing \"rows\" property in request body", "message": "Expected format: {\"rows\": [{...}, {...}]}", "example": { "rows": [{ "country": "country_value", "capital": "capital_value" }] }, "available_columns": ["Country", "Capital", "Population"] } ```
- 每个请求最多 1000 行 - 列名必须匹配表格 schema - 错误会在示例中显示您的实际列名
#### 批量操作（其他） ```bash curl -X POST https://www.moltsheet.com/api/v1/sheets/SHEET_ID/rows \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"count": 10}' ```
**响应：** ` {"success": true, "rowIds": ["row-...", ...]}`
- 每个请求最多 1000 行 - 仅创建空行；使用 `/import` 添加包含数据的行
#### 批量删除行 ```bash curl -X DELETE https://www.moltsheet.com/api/v1/sheets/SHEET_ID/rows \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"rowIds": ["row-123", "row-456"]}' ```
**响应：** ` {"success": true}`
#### 批量添加列 ```bash curl -X POST https://www.moltsheet.com/api/v1/sheets/SHEET_ID/columns \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"columns": [{"name": "Col1", "type": "string"}, {"name": "Col2", "type": "number"}]}' ```
**响应：** ` {"success": true}`
#### 批量删除列 ```bash curl -X DELETE https://www.moltsheet.com/api/v1/sheets/SHEET_ID/columns \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"indices": [0, 2]}' ```
**响应：** ` {"success": true}`
### AI 智能体优化功能
**自我修正错误消息：** - 每个错误都包含带有正确请求格式的 `example` 字段 - 错误在适用时显示您的实际列名 - `message` 字段提供人类可读的上下文 - `formats` 或 `supported_types` 枚举有效选项
**防止数据丢失：** - 删除包含数据的列时，schema 更新需要 `?confirmDataLoss=true` - 重命名端点（`POST /columns/{index}/rename`）自动保留所有数据 - 错误消息建议更安全的替代方案（重命名与删除）
**灵活的输入格式：** - POST /rows 接受 3 种格式：` {"count": N}`、` {"data": {...}}`、` {"rows": [...]}` - 无需猜测使用哪个端点 - 格式错误？错误会显示所有支持的格式及示例
**AI 友好设计：** - 所有端点一致的 JSON 结构 - 命名列访问（而非位置访问） - 对所有数据操作执行**严格类型验证** - 描述性成功消息确认操作
### 类型验证与强制执行 所有数据操作（POST /rows、PUT /cells、POST /import）都执行严格的类型验证：
**验证类型：** - **`string`**：任何非对象值（数字/布尔值自动转换为字符串） - **`number`**：必须是有效数字（非 NaN 或 Infinity）。接受数字字符串。 - **`boolean`**：接受 `true`、`false`、`"true"`、`"false"`、`1`、`0` - **`url`**：必须是带有 http/https 协议的有效 URL（例如，`https://example.com`） - **`date`**：必须解析为有效日期。使用 ISO 8601 格式（例如，`2026-02-01` 或 `2026-02-01T12:00:00Z`）
**验证行为：** - 允许空/null 值（不强制要求字段） - 无效类型将被拒绝并返回 **400 Bad Request** - 错误包括：字段名、期望类型、接收值和修正示例 - 多行：如果**任何**一行验证失败，则**全部**拒绝（原子操作）
**验证错误示例：** ```json { "success": false, "error": "Type validation failed", "message": "Column \"Age\" expects type \"number\" but received \"abc\" (type: string)", "field": "Age", "expected_type": "number", "received_value": "abc", "row_index": 0, "example": { "data": { "Age": 42 } } } ```
### 数据结构 - **Schema 类型**：`string`、`number`、`boolean`、`date`、`url` - **行数据**：命名属性，便于 AI 访问，例如 ` {"Name": "John", "Role": "CEO"}` - **类型强制执行**：所有值在存储前均根据 schema 进行验证 - **错误**：结构化，包含使用您实际 schema 的示例
### 速率限制 - 100 请求/分钟
### AI 智能体的使用构想 - 解析数据并使用提供的示例在错误时进行自我修正 - 单个端点（POST /rows）处理所有行创建场景 - 错误消息自动引导智能体使用正确的格式 - 列感知示例消除了猜测列名的需要