# motherduck-rest-api
> Administer MotherDuck service accounts, tokens, Ducklings, and Dive embed sessions through the control-plane REST API.
Administer MotherDuck service accounts, tokens, Ducklings, and Dive embed sessions through the control-plane REST API.

[Utility skill](/sql-reference/agent-skills/#utility-skills) · [View source on GitHub](https://github.com/motherduckdb/agent-skills/tree/v3.0.0/skills/motherduck-rest-api)

:::info

This page shows the skill's `SKILL.md`: the instructions a coding agent loads when a task matches the description above. To install every MotherDuck skill in Claude Code, Codex, Cursor, or Gemini CLI, see [Install MotherDuck Skills](/key-tasks/ai-and-motherduck/agent-skills/). To install only this skill with the [Skills CLI](https://github.com/vercel-labs/skills), run:

```bash
npx -y skills add motherduckdb/agent-skills --skill motherduck-rest-api --yes --global
```

:::

## 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. `GET /v1/users` lists every user and service account in the org; filter with `is_service_account` and `is_deprovisioned` and page with `limit`/`offset`. Use it for access reviews and to find a service account before creating a duplicate.
- Service accounts and access tokens accept an optional, searchable description. Set one that names the workload and owner; check the current API spec for the field name.
- For the Terraform resources, state rules, and setup archetypes, read `references/ACCESS_CONTROL_SETUPS.md` in [`motherduck-security-governance`](/sql-reference/agent-skills/motherduck-security-governance/).
- For repeatable provisioning (environments, partner or per-customer setups), prefer the Terraform provider `motherduckdb/motherduck` over scripted REST calls. It authenticates with `MOTHERDUCK_TOKEN`, plus `MOTHERDUCK_ADMIN_TOKEN` for service accounts, tokens, and Duckling configuration.
- 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.
- Treat agent/account signup (`motherduck new` or the public signup flow) as separate from the organization Admin REST API. Never create an account because an admin token is unavailable.
- For Dive embed sessions, keep `initial_state` JSON-serializable and within the documented size limits; validate iframe state, navigation, and export messages in the host application.

## Workflow

1. Identify whether the task is service-account provisioning, token management, Duckling sizing, active-account inspection, or Dive embedding.
2. Resolve the admin token from the existing environment and identify the target `username` or `dive_id`; ask only when a required value cannot be discovered, and never invent production identifiers.
3. 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.
4. For Duckling config changes, read the current config first, then update both `read_write` and `read_scaling` because the `PUT` payload requires both.
5. Preserve response fields that are only returned once, especially newly created token strings and embed session strings.
6. Surface API errors by status and response body; do not hide `400`, `401`, `403`, `404`, or `500` responses behind success-shaped fallbacks.
7. If the connected MotherDuck MCP server lists user-admin tools (such as `create_service_account`), prefer them over raw HTTP and call `get_user_admin_guide` first when it is listed. Many MCP setups do not expose them; then use the REST API directly. The MCP column in [`references/REST_API_GUIDE.md`](https://github.com/motherduckdb/agent-skills/blob/v3.0.0/skills/motherduck-rest-api/references/REST_API_GUIDE.md) maps the names.

For answer, review, or planning requests, inspect and report without mutating the control plane. For create or update requests, perform the requested in-scope operation and verify the response; retain confirmation for destructive deletes or broader administrative changes.

## References

Read only the reference sections needed for the current task.

- Read [`references/REST_API_GUIDE.md`](https://github.com/motherduckdb/agent-skills/blob/v3.0.0/skills/motherduck-rest-api/references/REST_API_GUIDE.md) for endpoint summaries, MCP tool mapping, curl examples, validation limits, and operational gotchas.

## Related skills

Load related skills only for missing capabilities; reuse established context.

- [`motherduck-query`](/sql-reference/agent-skills/motherduck-query/) for SQL and data-plane query work
- [`motherduck-connect`](/sql-reference/agent-skills/motherduck-connect/) for connection tokens and application connection posture
- [`motherduck-security-governance`](/sql-reference/agent-skills/motherduck-security-governance/) for admin-token handling, service-account posture, and access-boundary questions
- [`motherduck-create-dive`](/sql-reference/agent-skills/motherduck-create-dive/) for designing Dives before minting embed sessions

## Files in this skill

The agent reads these files when the instructions above point to them.

- [`references/REST_API_GUIDE.md`](https://github.com/motherduckdb/agent-skills/blob/v3.0.0/skills/motherduck-rest-api/references/REST_API_GUIDE.md)

## Docs this skill draws on

- [api.motherduck.com/docs/specs](https://api.motherduck.com/docs/specs)
- [MotherDuck REST API](https://motherduck.com/docs/sql-reference/rest-api/motherduck-rest-api/)
- [Create an access token for a user](https://motherduck.com/docs/sql-reference/rest-api/users-create-token/)
- [Service accounts](https://motherduck.com/docs/key-tasks/service-accounts-guide/)
- [Duckling sizes](https://motherduck.com/docs/about-motherduck/billing/duckling-sizes/)
- [Read Scaling](https://motherduck.com/docs/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/)
- [Embedding Dives in your web application](https://motherduck.com/docs/key-tasks/dives/embedding-dives/)
- [motherduck.com/blog/introducing-embedded-dives](https://motherduck.com/blog/introducing-embedded-dives/)
- [Manage service accounts and tokens](https://motherduck.com/docs/key-tasks/service-accounts-guide/manage-service-accounts-and-tokens/)
- [Terraform](https://motherduck.com/docs/integrations/dev-tools/terraform/)


---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

URL-encode query parameter values and send a GET request:

```text
GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fsql-reference%2Fagent-skills%2Fmotherduck-rest-api%2F&page_title=motherduck-rest-api&text=<url-encoded user feedback, max 2000 characters>
```

Optionally append `&source=<url-encoded interface identifier>` such as `claude.ai` or `chatgpt`.

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed query parameters, and `429` when rate-limited.
