REST API Administration

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.

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.

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.