Canvas Workbench · API Reference

API 参考

Canvas Workbench REST API 合约文档。涵盖认证、工作空间端点、卡片管理与快速开始流程。

1. 概述

  • API 版本：0.2.0-api
  • 标准路由前缀：/api/v1
  • 默认基础 URL：http://127.0.0.1:8787
  • 旧版 /v1/* 路由已移除

环境变量：

CANVAS_WORKBENCH_API_HOST      (default 127.0.0.1)
CANVAS_WORKBENCH_API_PORT      (default 8787)
CANVAS_WORKBENCH_API_BASE_URL  (optional override)
CANVAS_WORKBENCH_WEB_ORIGIN    (default http://127.0.0.1:5173)

2. 响应协议

所有 /api/v1/* 路由统一返回以下结构：

// Success
{ "data": ... , "meta"?: { "message": string } }

// Error
{ "error": { "code": string, "message": string, "details"?: any } }

HTTP 状态码映射：

  • 400 → bad_request
  • 401 → unauthorized
  • 403 → forbidden
  • 404 → not_found
  • 409 → conflict
  • 429 → rate_limited
  • 5xx → internal_error

3. 认证模型

默认本地模式为免登录使用。工作空间读写端点不强制要求 Authorization 请求头，使用内置本地工作空间。若提供 API Key，服务器仍会校验并强制执行 scope 权限。

支持两种令牌类型：

  1. Access Token（会话令牌）— 用于账户/会话端点，Header: Authorization: Bearer <ACCESS_TOKEN>，通过 POST /api/v1/auth/demo-login 签发，有效期 30 天。
  2. API Key — 工作空间端点可选使用，Header: Authorization: Bearer <API_KEY>，通过 POST /api/v1/auth/api-keys 签发，Scope: canvas:read, canvas:write。

4. 公开端点（无需认证）

GET/health

返回服务健康状态与运行时配置。

GET/openapi.json

返回 OpenAPI 3.1 描述文档。

GET/llms-api.txt

返回纯文本 API 速查表，供 LLM/工具使用。

5. 会话端点

POST/api/v1/auth/demo-login

演示登录，创建账户（如不存在）并签发会话令牌。

{
  "name": "Open Canvas User",
  "email": "user@example.com",
  "provider": "demo",
  "avatarUrl": "https://..."
}
GET/api/v1/auth/me

校验当前会话令牌并返回账户信息。

POST/api/v1/auth/api-keys

为当前账户创建 API Key。

GET/api/v1/auth/api-keys

列出当前账户的所有 API Key。

POST/api/v1/auth/api-keys/:keyId/revoke

撤销指定 API Key。

6. 工作空间端点

本地模式下无需认证即可访问；使用 API Key 时需携带对应 scope。

GET /api/v1/state?full=1

Scope: canvas:read。full=1 返回完整卡片数据，否则仅返回 cardCount。

GET /api/v1/config

Scope: canvas:read。返回 apiBaseUrl、webOrigin、workspaceId、supportedKinds 等配置。

POST /api/v1/grids

Scope: canvas:write。创建新网格，可选 activate: true 设为当前活跃网格。

{
  "id": "grid-work",
  "name": "Work",
  "activate": true
}

PATCH /api/v1/grids/:gridId

Scope: canvas:write。重命名网格或切换活跃状态。

DELETE /api/v1/grids/:gridId

Scope: canvas:write。删除网格；若删除的是活跃网格，服务器自动提升邻近网格为活跃。禁止删除最后一个网格。

POST /api/v1/assets

Scope: canvas:write。上传二进制资源（图片/视频/PDF），服务器返回带签名令牌的公开 URL。

{
  "id": "asset-image-1",
  "name": "photo.png",
  "type": "image/png",
  "dataUrl": "data:image/png;base64,..."
}

GET /api/v1/assets/:assetId

公开获取资源，需携带上传响应 URL 中的 token 查询参数。

DELETE /api/v1/assets/:assetId

Scope: canvas:write。删除资源文件及元数据。

POST /api/v1/cards

Scope: canvas:write。创建卡片。支持的 kind：note、hint、image、video、pdf、todo、calendar。

卡片策略：note 可重复创建；todo 和 calendar 每个网格为单例（singleton），已存在时复用。

{
  "kind": "note",
  "gridId": "grid-...",
  "title": "Quick note",
  "content": "Hello",
  "x": 320, "y": 180,
  "width": 420, "height": 300,
  "activateGrid": true
}

PATCH /api/v1/cards/:cardId

Scope: canvas:write。更新卡片字段：title、content、x、y、width、height。

POST /api/v1/cards/:cardId/append-note

Scope: canvas:write。追加文本到现有卡片内容末尾（带换行）。

{ "text": "append this line" }

7. 快速开始

1. 登录获取访问令牌：

curl -X POST http://127.0.0.1:8787/api/v1/auth/demo-login \
  -H "Content-Type: application/json" \
  -d '{"name":"Demo User","email":"demo@example.com","provider":"demo"}'

2. 创建 API Key：

curl -X POST http://127.0.0.1:8787/api/v1/auth/api-keys \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Open Canvas API Key","scopes":["canvas:read","canvas:write"]}'

3. 创建卡片：

curl -X POST http://127.0.0.1:8787/api/v1/cards \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"kind":"note","title":"From API","content":"Auto created"}'

8. 数据持久化

  • 本地运行时数据库文件：.runtime/api-db.json
  • 存储实体：accounts、sessions、apiKeys、workspaces

9. 兼容性说明

  • 仅使用 /api/v1/* 路由。
  • 不要使用已移除的旧版 /v1/* 端点。
  • 工具验证请优先使用 GET /openapi.json。

更多文档