motherduckdb/agent-skills / plugins/motherduck-skills-claude/skills/motherduck-rest-api
motherduck-rest-api
VerifiedAdminister MotherDuck service accounts, tokens, Ducklings, and Dive embed sessions through the control-plane REST API.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.3 KB |
| references/REST_API_GUIDE.md | markdown | 11.4 KB |
references/REST_API_GUIDE.md
View on GitHub# MotherDuck REST API Guide
Use this guide for control-plane workflows against `https://api.motherduck.com`. Agent signup through `motherduck new` or the public signup flow is a separate product surface and is not an Admin REST API fallback.
The REST API is not the SQL query path. Use it for organization administration, service-account provisioning, supported token lifecycle work, Duckling configuration, active-account inspection, and Dive embed sessions.
## MotherDuck MCP
When the MotherDuck MCP server is connected and lists user-admin tools, prefer MCP
admin tools over curl. Check the tool list first; many MCP setups do not expose them. The server exchanges the caller's credential for a regional SLT and
calls `api.<region>.motherduck.com`, not the global routing host. Call `get_user_admin_guide`
for the in-session copy of this guide.
Confirm destructive MCP calls (`delete_user`, `invalidate_access_token`) before invoking.
Store newly minted token secrets immediately — they are shown once.
## Contents
- [Authentication](#authentication)
- [Endpoint Summary](#endpoint-summary)
- [Service Account Provisioning](#service-account-provisioning)
- [Token Lifecycle](#token-lifecycle)
- [Duckling Configuration](#duckling-configuration)
- [Active Accounts](#active-accounts)
- [Dive Embed Sessions](#dive-embed-sessions)
- [Error Responses](#error-responses)
## Authentication
All endpoints use bearer authentication:
```bash
export MD_API="https://api.motherduck.com"
export MOTHERDUCK_ADMIN_TOKEN="<admin-token-from-secret-manager>"
curl -fsS \
-H "Authorization: Bearer ${MOTHERDUCK_ADMIN_TOKEN}" \
"${MD_API}/v1/active_accounts"
```
Operational rules:
- Use a read-write access token for an organization Admin for admin/control-plane calls.
- Keep `MOTHERDUCK_ADMIN_TOKEN` in a backend secret manager or local environment variable, never source code.
- Do not send admin bearer tokens to browsers.
- Do not use read-scaling tokens for REST API administration.
- Log status codes and error `code` or `message`, but do not log bearer tokens or newly minted access tokens.
## Endpoint Summary
| Operation | MCP tool (only if the server lists it) | Method and path | Notes |
|---|---|---|---|
| Load admin guide | `get_user_admin_guide` | — | In-session copy of this guide. |
| List users | — | `GET /v1/users` | Users and service accounts; filters `is_service_account`, `is_deprovisioned`; `limit` (max 1000) and `offset`; returns `users` and `total_count`. |
| Create service account | `create_service_account` | `POST /v1/users` | Username unique in org; creates a service account only. |
| Delete user | `delete_user` | `DELETE /v1/users/{username}` | Destructive; confirm first. |
| Create token | `create_access_token` | `POST /v1/users/{username}/tokens` | Secret returned once. |
| List tokens | `list_access_tokens` | `GET /v1/users/{username}/tokens` | Metadata only. |
| Delete token | `invalidate_access_token` | `DELETE /v1/users/{username}/tokens/{token_id}` | Use token `id`, not the secret. |
| Get Duckling config | `get_duckling_config` | `GET /v1/users/{username}/instances` | Requires admin role. |
| Set Duckling config | `set_duckling_config` | `PUT /v1/users/{username}/instances` | Requires both `read_write` and `read_scaling`. |
| Get active accounts | — | `GET /v1/active_accounts` | Verify lifecycle status and response shape in the current OpenAPI spec. |
| Create Dive embed session | `create_dive_embed_session` | `POST /v1/dives/{dive_id}/embed-session` | Requires service-account `username`; optional `session_hint`. |
## Service Account Provisioning
Create a service account:
```bash
curl -fsS -X POST \
-H "Authorization: Bearer ${MOTHERDUCK_ADMIN_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"username":"analytics_app"}' \
"${MD_API}/v1/users"
```
Username constraints from the runtime validator:
- `3..255` characters
- starts with a Unicode letter
- contains only Unicode letters, digits, and underscores
- unique within the organization
- case-insensitive for identity
List users and service accounts for an access review:
```bash
curl -fsS \
-H "Authorization: Bearer ${MOTHERDUCK_ADMIN_TOKEN}" \
"${MD_API}/v1/users?is_service_account=true&is_deprovisioned=false&limit=100&offset=0"
```
Each entry includes `username`, `is_service_account`, `is_deprovisioned`, and `roles`. Page until you have read `total_count` entries.
For environments that should be reproducible, manage service accounts, tokens, and Duckling configuration with the Terraform provider instead of one-off calls, and keep Terraform state in an encrypted remote backend because it can hold token values.
`POST /v1/users` creates service accounts, not arbitrary human users or arbitrary-role users. Do not document role updates, service-account impersonation, share attachment routes, or attachment management as public REST API capabilities unless the current public spec exposes them.
Delete a user only after explicit confirmation:
```bash
curl -fsS -X DELETE \
-H "Authorization: Bearer ${MOTHERDUCK_ADMIN_TOKEN}" \
"${MD_API}/v1/users/analytics_app"
```
The delete operation permanently deletes the user and all of their data.
## Token Lifecycle
Create a read-write token:
```bash
curl -fsS -X POST \
-H "Authorization: Bearer ${MOTHERDUCK_ADMIN_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"name":"backend-api","ttl":2592000,"token_type":"read_write"}' \
"${MD_API}/v1/users/analytics_app/tokens"
```
Create a read-scaling token:
```bash
curl -fsS -X POST \
-H "Authorization: Bearer ${MOTHERDUCK_ADMIN_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"name":"embed-read-scaling","ttl":86400,"token_type":"read_scaling"}' \
"${MD_API}/v1/users/analytics_app/tokens"
```
Request fields:
- `name`: required, `1..255` characters
- `ttl`: optional token lifetime in integer seconds, `300..31536000`; omit it for a token that remains valid until revoked
- `token_type`: optional, `read_write` or `read_scaling`; defaults to `read_write`
Response fields include:
- `token`: the access token secret, only returned on creation
- `id`: token UUID used for invalidation
- `name`, `expire_at`, `created_ts`
- `read_only`
- `token_type`: `read_write` or `read_scaling`
List token metadata:
```bash
curl -fsS \
-H "Authorization: Bearer ${MOTHERDUCK_ADMIN_TOKEN}" \
"${MD_API}/v1/users/analytics_app/tokens"
```
Invalidate a token:
```bash
curl -fsS -X DELETE \
-H "Authorization: Bearer ${MOTHERDUCK_ADMIN_TOKEN}" \
"${MD_API}/v1/users/analytics_app/tokens/00000000-0000-0000-0000-000000000000"
```
Token handling gotchas:
- Through the API, users can create tokens for themselves and admins can create tokens for service accounts.
- Admins cannot create tokens for other non-service-account members through the API.
- If a service account is newly created through the API, connect once with that service account's read-write token before relying on read-scaling tokens.
- The token secret is not returned by the list endpoint.
- Store the `id` separately from the token secret so rotation and invalidation can target the correct token.
- Delete tokens by `id`; do not rely on labels or names as stable deletion identifiers.
- Prefer short TTLs for automation that can rotate tokens cleanly.
- Use read-scaling tokens for read-heavy serving paths that should not use the read-write Duckling.
## Duckling Configuration
The endpoint path uses the legacy word `instances`, but it configures Ducklings.
Read a user's current Duckling configuration:
```bash
curl -fsS \
-H "Authorization: Bearer ${MOTHERDUCK_ADMIN_TOKEN}" \
"${MD_API}/v1/users/analytics_app/instances"
```
Set read-write and read-scaling configuration:
```bash
curl -fsS -X PUT \
-H "Authorization: Bearer ${MOTHERDUCK_ADMIN_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"config": {
"read_write": {
"instance_size": "standard",
"cooldown_seconds": 600
},
"read_scaling": {
"instance_size": "standard",
"flock_size": 2,
"cooldown_seconds": 600
}
}
}' \
"${MD_API}/v1/users/analytics_app/instances"
```
Allowed `instance_size` values:
- `pulse`
- `standard`
- `jumbo`
- `mega`
- `giga`
Validation limits:
- `read_write.instance_size` is required.
- `read_scaling.instance_size` and `read_scaling.flock_size` are required.
- The schema allows `read_scaling.flock_size` values between `0` and `64`, but effective limits are plan and organization specific.
- `cooldown_seconds`, when supplied, must be an integer between `60` and `86400`.
- `cooldown_seconds` cannot be set for `pulse` Ducklings.
Default cooldown behavior:
- `standard`: `60`
- `jumbo`: `60`
- `mega`: `300`
- `giga`: `600`
- `pulse`: no cooldown
Use a read-before-write posture because `PUT /v1/users/{username}/instances` requires the full `config` object with both `read_write` and `read_scaling`. When switching an existing non-Pulse config to `pulse`, remove copied `cooldown_seconds` fields before sending the `PUT`.
A `400` response such as `Invalid config for tier ...` can mean the payload exceeded plan or organization limits even when it satisfies the OpenAPI schema.
## Active Accounts
Inspect active accounts and active Ducklings:
```bash
curl -fsS \
-H "Authorization: Bearer ${MOTHERDUCK_ADMIN_TOKEN}" \
"${MD_API}/v1/active_accounts"
```
The response has an `accounts` array. Each account includes:
- `username`
- `ducklings[]` with `id`, `type`, and `status`
Duckling fields:
- `id`: `rw` or `rs.N`
- `type`: `read_write` or `read_scaling`
- `status`: `active` or `cooldown`
Check the current OpenAPI spec for this endpoint's lifecycle status and response shape before building operational automation around it.
## Dive Embed Sessions
Create an embed session for a Dive:
```bash
curl -fsS -X POST \
-H "Authorization: Bearer ${MOTHERDUCK_ADMIN_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"username":"analytics_app","session_hint":"customer-123"}' \
"${MD_API}/v1/dives/00000000-0000-0000-0000-000000000000/embed-session"
```
Request fields:
- `username`: required service account username within the organization
- `session_hint`: optional non-empty hint used to reuse the same read-scaling session across embed requests
Verify embedded-Dive entitlements against current docs. An organization without embed access may receive `403`; preserve the actual status and response body rather than assuming the cause.
The response contains an opaque `session` string backed by a short-lived read-scaling token that runs as the service account. Treat it as a runtime credential:
- do not persist it longer than needed
- do not log it
- do not confuse it with a user access token
- expect it to expire after 24 hours
Frontend iframe shape:
```html
<iframe
src="https://embed-motherduck.com/sandbox/#session=<session_from_backend>"
sandbox="allow-scripts allow-same-origin"
></iframe>
```
If the host site has a restrictive Content Security Policy, add `https://embed-motherduck.com` to `frame-src`.
## Error Responses
Standard error responses use this shape:
```json
{
"code": "BAD_REQUEST",
"message": "Bad Request",
"issues": [
{
"message": "field-specific validation message"
}
]
}
```
Expected status codes:
- `400`: malformed request or validation failure
- `401`: invalid credentials
- `403`: authenticated but unauthorized
- `404`: target user, token, Dive, or resource not found
- `500`: internal service error
Do not convert these into silent success. Preserve the status code and response body for the caller or operator.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |