Motherduck Rest Api

---
name: motherduck-rest-api
description: MotherDuck REST API control-plane reference. Use when calling api.motherduck.com or MotherDuck MCP admin tools to provision service accounts, manage tokens, configure Ducklings, or mint Dive embed sessions. Not for SQL or data-plane query work.
license: MIT
---

# 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; SQL and data-plane queries go through a database connection, not the REST API.
- 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.