---
id: motherduck-rest-api
title: "MotherDuck REST API"
description: REST API reference for managing MotherDuck resources including databases, users, and access tokens.
sidebar_label: Introduction
sidebar_position: 0
hide_title: true
custom_edit_url: null
---


import ApiLogo from "@theme/ApiLogo";
import Admonition from '@theme/Admonition';
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";
<span
  className={"theme-doc-version-badge badge badge--secondary"}
  children={"Version: 1.0.0"}
>
</span>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"MotherDuck REST API"}
>
</Heading>

::::warning[Preview Feature]
The REST API methods are in 'Preview' and may change in the future
::::

To better support scenarios that require some flexibility or dynamic configuration around
managing a MotherDuck organization we are exposing an OpenAPI endpoint with some new functionality.
At the moment it enables limited management of users and tokens through HTTP without requiring a
DuckDB + MotherDuck client to be running.

All of the methods are authenticated using a Read/Write token of a user with the `Admin` role within your MotherDuck Organization
and passing it through the `Authorization` header with a value of `Bearer {TOKEN}`.

::::info[Service Account Management]
  You can use this REST API to programmatically manage service accounts, including their creation, token generation, and Duckling configuration.
  For a detailed walkthrough, see [Create and configure service accounts](/key-tasks/service-accounts-guide/create-and-configure-service-accounts/).
::::

If you would like to generate your own OpenAPI client the spec file is located at https://api.motherduck.com/docs/specs


## Included pages

- [Create a Dive embed session for a service account](https://motherduck.com/docs/sql-reference/rest-api/dashboards-create-embed-session): Creates an embed session for the specified Dive.
- [Create an access token for a user](https://motherduck.com/docs/sql-reference/rest-api/users-create-token): Create an access token for a user
- [Create new user](https://motherduck.com/docs/sql-reference/rest-api/users-create-service-account): Create user is restricted to creating a user with a 'Member' role
- [Delete a user](https://motherduck.com/docs/sql-reference/rest-api/users-delete): Permanently delete a user and all of their data. THIS CANNOT BE UNDONE
- [Get active accounts](https://motherduck.com/docs/sql-reference/rest-api/ducklings-get-active-accounts): [Preview] Get active accounts in an organization along with active Ducklings per account. Requires 'Admin' role
- [Get user Duckling configuration](https://motherduck.com/docs/sql-reference/rest-api/ducklings-get-duckling-config-for-user): Gets Duckling (instance) configuration for a user. Requires 'Admin' role.
- [Invalidate a user access token](https://motherduck.com/docs/sql-reference/rest-api/users-delete-token): Invalidate a user access token
- [List a user's access tokens](https://motherduck.com/docs/sql-reference/rest-api/users-list-tokens): List a user's access tokens
- [Set user Duckling configuration](https://motherduck.com/docs/sql-reference/rest-api/ducklings-set-duckling-config-for-user): Sets Duckling (instance) configuration for a user. Requires 'Admin' role



---

## Docs feedback

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

Payload:

```json
{
  "page_path": "/sql-reference/rest-api/motherduck-rest-api/",
  "page_title": "MotherDuck REST API",
  "text": "<the user's feedback, max 2000 characters>",
  "source": "<optional identifier for your interface, for example 'claude.ai' or 'chatgpt'>"
}
```

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