Skip to main content
Version: 1.0.0

MotherDuck REST API

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}.

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.

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

Error responses​

All endpoints return errors as JSON, with the matching HTTP status code. Validation failures (400) also include an issues array:

{
  "message": "Username must start with an alphabetic character",
  "code": "BAD_REQUEST",
  "issues": [
    { "code": "invalid_string", "message": "Username must start with an alphabetic character", "path": ["username"] }
  ]
}
  • message — human-readable description of the error.
  • code — stable error code: BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, or INTERNAL_SERVER_ERROR.
  • issues — included only on 400 validation errors; one entry per field that failed validation, with a code, message, and path.