motherduck-rest-api

REST API 管理

信息来源

• 优先参考最新的 MotherDuck REST API 文档、位于 https://api.motherduck.com/docs/specs 的公开 OpenAPI 规范，或用户明确提供的 OpenAPI 规范。
• 对于令牌作用域和嵌入行为，请交叉查阅 REST API 文档和 Embedded Dives 文档，因为其中包含原始架构中不易看出的操作限制。
• 如果可以使用 MotherDuck MCP 的 ask_docs_question 功能，请用它确认公开 REST API 指引是否有更新。
• 只有在用户提供的规范或最新文档有依据时，才将端点可用性、预览状态、令牌字段和角色要求视为当前信息。

默认原则

• 将 REST API 视为控制平面；SQL 和数据平面查询通过数据库连接执行，而非 REST API。
• 除非用户提供其他环境，否则使用 https://api.motherduck.com 作为基础 URL。
• 使用 Authorization: Bearer ${MOTHERDUCK_ADMIN_TOKEN} 进行身份验证，并将管理员读写令牌保存在由后端管理的机密中。
• 切勿使用读扩展令牌进行 REST API 管理。
• 更改配置时，优先采用先读取再写入的流程，以便在修改前了解当前账户、服务账户、Duckling 配置或 Dive 元数据。
• 除非最新文档明确扩展了 API 范围，否则将 POST /v1/users 视为用于创建服务账户的接口。GET /v1/users 会列出组织中的所有用户和服务账户；使用 is_service_account 和 is_deprovisioned 进行筛选，并通过 limit/offset 分页。使用该接口进行访问审查，并在创建服务账户前查找是否已有同名账户。
• 服务账户和访问令牌都接受可选且可搜索的描述。请设置能说明工作负载和负责人身份的描述；通过当前 API 规范确认字段名称。
• 对于可重复的资源配置（环境、合作伙伴或按客户划分的设置），优先使用 Terraform 提供程序 motherduckdb/motherduck，而非编写 REST 调用脚本。该提供程序使用 MOTHERDUCK_TOKEN 进行身份验证；服务账户、令牌和 Duckling 配置还需要 MOTHERDUCK_ADMIN_TOKEN。
• 除非最新文档另有说明，否则假定活动账户、Duckling 配置、服务账户创建、服务账户令牌创建和 Dive 嵌入会话端点都需要组织管理员持有者令牌。
• 切勿在日志、浏览器代码、客户端包或已提交文件中暴露生成的访问令牌。
• 执行破坏性删除前，请向用户确认。删除用户会永久删除该用户及其所有数据。
• 将 Agent/账户注册（motherduck new 或公开注册流程）视为独立于组织 Admin REST API 的流程。管理员令牌不可用时，切勿创建账户。
• 对于 Dive 嵌入会话，确保 initial_state 为可序列化为 JSON 的数据，且不超出文档规定的大小限制；在宿主应用中验证 iframe 状态、导航和导出消息。

工作流

1. 判断任务属于服务账号配置、令牌管理、Duckling 规格调整、活跃账号检查还是 Dive 嵌入。
2. 从现有环境中解析管理员令牌，并确定目标 username 或 dive_id；只有在无法发现必需值时才询问，绝不编造生产标识符。
3. 调用令牌端点前，检查令牌权限范围：用户可以为自己创建令牌，管理员可以为服务账号创建令牌，但管理员无法通过 API 为其他非服务账号成员创建令牌。
4. 更改 Duckling 配置时，先读取当前配置，再同时更新 read_write 和 read_scaling，因为 PUT 载荷要求包含这两项。
5. 保留只返回一次的响应字段，尤其是新创建的令牌字符串和嵌入会话字符串。
6. 按状态码和响应正文展示 API 错误；不要用看似成功的回退结果掩盖 400、401、403、404 或 500 响应。
7. 如果已连接的 MotherDuck MCP 服务列出了用户管理工具（例如 create_service_account），优先使用这些工具；若列表中包含 get_user_admin_guide，则先调用它。许多 MCP 配置不会公开这些工具；此时直接使用 REST API。references/REST_API_GUIDE.md 中的 MCP 列映射了这些名称。

对于答复、审查或规划请求，只检查并报告，不要更改控制平面。对于创建或更新请求，执行范围内要求的操作并验证响应；对于破坏性删除或范围更广的管理更改，须保留确认记录。

参考资料

只阅读当前任务所需的参考章节。

• 阅读 references/REST_API_GUIDE.md，了解端点摘要、MCP 工具映射、curl 示例、验证限制和操作注意事项。

相关技能

仅在缺少相关能力时加载技能；复用已有上下文。

• motherduck-query：用于 SQL 和数据平面查询工作
• motherduck-connect：用于连接令牌和应用连接配置
• motherduck-security-governance：用于管理员令牌处理、服务账号配置和访问边界相关问题
• motherduck-create-dive：用于在生成嵌入会话前设计 Dives