motherduck-rest-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

REST API Administration

REST API 管理

Use this skill when the user needs to manage MotherDuck service accounts, supported token operations, Duckling configuration, active accounts, or Dive embed sessions through the REST API.

当用户需要通过REST API管理MotherDuck服务账号、支持的令牌操作、Duckling配置、活跃账号或Dive嵌入会话时，使用此技能。

Source Of Truth

权威来源

Prefer current MotherDuck REST API documentation, the public OpenAPI spec at
```
https://api.motherduck.com/docs/specs
```
, or an explicit OpenAPI spec supplied by the user.
For token scope and embed behavior, cross-check the REST API docs and the Embedded Dives docs because they include operational constraints not obvious from the raw schema.
If the MotherDuck MCP
```
ask_docs_question
```
feature is available, use it to check whether public REST API guidance has changed.
Treat endpoint availability, preview status, token fields, and role requirements as current only when backed by the supplied spec or current docs.

优先参考当前的MotherDuck REST API文档、位于
```
https://api.motherduck.com/docs/specs
```
的公开OpenAPI规范，或用户提供的明确OpenAPI规范。
对于令牌范围和嵌入行为，交叉核对REST API文档和Embedded Dives文档，因为它们包含原始架构中不明显的操作约束。
如果MotherDuck MCP的
```
ask_docs_question
```
功能可用，使用它检查公开REST API指南是否有变更。
只有当端点可用性、预览状态、令牌字段和角色要求有提供的规范或当前文档支持时，才将其视为有效。

Default Posture

默认准则

Treat the REST API as the control plane. Use
```
motherduck-query
```
for SQL and data-plane work.
Use
```
https://api.motherduck.com
```
as the base URL unless the user provides another environment.
Authenticate with
```
Authorization: Bearer ${MOTHERDUCK_ADMIN_TOKEN}
```
and keep admin read-write tokens in backend-managed secrets.
Never use read-scaling tokens for REST API administration.
Prefer read-before-write flows for configuration changes so the current account, service account, Duckling config, or Dive metadata is known before mutation.
Treat
```
POST /v1/users
```
as service-account creation unless current docs explicitly broaden the API.
Assume active-account, Duckling configuration, service-account creation, service-account token creation, and Dive embed-session endpoints require an organization admin bearer token unless current docs say otherwise.
Never expose generated access tokens in logs, browser code, client bundles, or committed files.
Confirm destructive deletes with the user. Deleting a user permanently deletes that user and all of their data.

将REST API视为控制平面。使用
```
motherduck-query
```
处理SQL和数据平面工作。
除非用户提供其他环境，否则使用
```
https://api.motherduck.com
```
作为基础URL。
使用
```
Authorization: Bearer ${MOTHERDUCK_ADMIN_TOKEN}
```
进行身份验证，并将管理员读写令牌存储在后端管理的密钥中。
切勿使用读取扩展令牌进行REST API管理。
对于配置变更，优先采用“先读后写”流程，以便在修改前了解当前账号、服务账号、Duckling配置或Dive元数据。
除非当前文档明确扩展了API用途，否则将
```
POST /v1/users
```
视为服务账号创建接口。
假设活跃账号、Duckling配置、服务账号创建、服务账号令牌创建和Dive嵌入会话端点需要组织管理员Bearer令牌，除非当前文档另有说明。
切勿在日志、浏览器代码、客户端包或已提交文件中暴露生成的访问令牌。
删除操作需与用户确认。删除用户将永久删除该用户及其所有数据。

Workflow

工作流程

Identify whether the task is service-account provisioning, token management, Duckling sizing, active-account inspection, or Dive embedding.
Confirm the admin token location and the target
```
username
```
or
```
dive_id
```
; never invent production identifiers.
Check token scope before calling token endpoints: users can create tokens for themselves, and admins can create tokens for service accounts, but admins cannot create tokens for other non-service-account members through the API.
For Duckling config changes, read the current config first, then update both
```
read_write
```
and
```
read_scaling
```
because the
```
PUT
```
payload requires both.
Preserve response fields that are only returned once, especially newly created token strings and embed session strings.
Surface API errors by status and response body; do not hide
```
400
```
,
```
401
```
,
```
403
```
,
```
404
```
, or
```
500
```
responses behind success-shaped fallbacks.

确定任务属于服务账号配置、令牌管理、Duckling规模调整、活跃账号检查还是Dive嵌入。
确认管理员令牌位置和目标
```
username
```
或
```
dive_id
```
；切勿编造生产环境标识符。
在调用令牌端点前检查令牌范围：用户可为自己创建令牌，管理员可为服务账号创建令牌，但管理员无法通过API为其他非服务账号成员创建令牌。
对于Duckling配置变更，先读取当前配置，然后同时更新
```
read_write
```
和
```
read_scaling
```
，因为
```
PUT
```
请求体需要这两个字段。
保留仅返回一次的响应字段，尤其是新创建的令牌字符串和嵌入会话字符串。
按状态码和响应体展示API错误；不要用伪装成成功的回退隐藏
```
400
```
、
```
401
```
、
```
403
```
、
```
404
```
或
```
500
```
响应。

Open Next

后续参考

```
references/REST_API_GUIDE.md
```
for endpoint summaries, auth headers, request payloads, curl examples, validation limits, and operational gotchas

```
references/REST_API_GUIDE.md
```
包含端点摘要、认证头、请求体、curl示例、验证限制和操作注意事项