从一间小屋开始

本教程使用 REST API 和 curl。每一步通过 MCP 操作时也完全相同，因为两者都由同一份操作目录生成，并经过与应用相同的权限检查。

创建连接

登录后，在控制面板中打开开发者（仅工作区所有者和管理员可用），选择新建连接。选择 REST API，保留默认只读权限（workspaces:read、catalog:read、worlds:read），并为本教程添加 worlds:write 和 worlds:publish。令牌只显示一次，请立即复制到你的密钥存储中。

同一页面的参考卡片会显示 REST 基础 URL、MCP 端点和 OpenAPI 契约。

export BASE="https://<your host>/api/v1"
export TOKEN="sw_rest_..."

找到工作区

每个令牌只属于一个工作区。列出工作区，取得其 id 和你的角色：

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/workspaces"
export WS="<data[0].id>"

接着查询这个工作区当前能做什么。每项能力都会说明，它是已实现、模拟运行、因缺少凭据受阻，还是正在等待决定：

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/workspaces/$WS/capabilities"

创建小屋草稿

从目录（GET /catalog/templates）选择一款设计，再创建草稿。每次写入都需要一个长度为16至128个字符的 Idempotency-Key；使用相同键和请求体重试，会返回原结果，而不会创建第二间小屋。

curl -s -X POST "$BASE/workspaces/$WS/worlds" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -H "Content-Type: application/json" \
  -d '{"handle":"my-first-casa","template_id":"pizza",
       "profile":{"display_name":"My first casa","bio":"Hello from the API.","content_language":"en"}}'

安全编辑

先读取小屋。响应带有 ETag 标头；提交更改时，将其作为 If-Match 发送回去。如果期间有人编辑过草稿，你会收到 412 revision_conflict，不会发生任何更改。

curl -s -i -H "Authorization: Bearer $TOKEN" "$BASE/workspaces/$WS/worlds/$WORLD"

curl -s -X PATCH "$BASE/workspaces/$WS/worlds/$WORLD" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -H 'If-Match: W/"<etag>"' \
  -H "Content-Type: application/json" \
  -d '{"profile":{"bio":"Edited over the API."}}'

发布并等待任务完成

发布需要最近一次读取中准确的 draft_revision_id 和 draft_digest，确保发布的就是你检查过的内容。接口返回 202 和一个任务；在新版本构建成功之前，上一版本会继续在线。

curl -s -X POST "$BASE/workspaces/$WS/worlds/$WORLD/publications" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -H "Content-Type: application/json" \
  -d '{"revision_id":"<draft_revision_id>","expected_digest":"<draft_digest>"}'

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/workspaces/$WS/jobs/$JOB"

轮询间隔不得短于 next_poll_after_seconds。状态为 completed 的任务，会返回线上页面的 canonical_url。任务数量不止几个时，优先使用 webhook，而不是轮询。

接下来去哪里

• 身份验证与权限范围：每项操作需要哪些权限。
• MCP：将智能体客户端连接到相同的操作。
• API 参考：约定、错误和 OpenAPI 契约。