{ "openapi": "3.0.3", "info": { "title": "MotherDuck REST API", "version": "1.0.0", "description": "REST API reference for managing MotherDuck resources including databases, users, and access tokens." }, "servers": [ { "url": "https://api.motherduck.com" } ], "paths": { "/v1/users/{username}/instances": { "get": { "operationId": "ducklings-getDucklingConfigForUser", "summary": "Get user Duckling configuration", "description": "Gets Duckling (instance) configuration for a service account or user account. Requires 'Admin' role.", "tags": [ "ducklings" ], "security": [ { "Authorization": [] } ], "parameters": [ { "in": "path", "name": "username", "description": "user within the organization", "schema": { "type": "string", "maxLength": 255, "description": "user within the organization" }, "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "read_write": { "type": "object", "properties": { "instance_size": { "type": "string", "enum": [ "pulse", "standard", "jumbo", "mega", "giga" ], "example": "standard" }, "cooldown_seconds": { "type": "integer", "minimum": 60, "maximum": 86400, "example": 60 } }, "required": [ "instance_size" ] }, "read_scaling": { "type": "object", "properties": { "instance_size": { "type": "string", "enum": [ "pulse", "standard", "jumbo", "mega", "giga" ], "example": "standard" }, "flock_size": { "type": "number", "minimum": 0, "maximum": 64, "example": 1 }, "cooldown_seconds": { "type": "integer", "minimum": 60, "maximum": 86400, "example": 60 } }, "required": [ "instance_size", "flock_size" ] } }, "required": [ "read_write", "read_scaling" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.BAD_REQUEST" } } } }, "401": { "description": "Invalid Credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.UNAUTHORIZED" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.FORBIDDEN" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.NOT_FOUND" } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.INTERNAL_SERVER_ERROR" } } } } } }, "put": { "operationId": "ducklings-setDucklingConfigForUser", "summary": "Set user Duckling configuration", "description": "Sets Duckling (instance) configuration for a service account or user account. Requires 'Admin' role.", "tags": [ "ducklings" ], "security": [ { "Authorization": [] } ], "parameters": [ { "in": "path", "name": "username", "description": "user within the organization", "schema": { "type": "string", "maxLength": 255, "description": "user within the organization" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "properties": { "read_write": { "type": "object", "properties": { "instance_size": { "type": "string", "enum": [ "pulse", "standard", "jumbo", "mega", "giga" ], "example": "standard" }, "cooldown_seconds": { "type": "integer", "minimum": 60, "maximum": 86400, "example": 60 } }, "required": [ "instance_size" ] }, "read_scaling": { "type": "object", "properties": { "instance_size": { "type": "string", "enum": [ "pulse", "standard", "jumbo", "mega", "giga" ], "example": "standard" }, "flock_size": { "type": "number", "minimum": 0, "maximum": 64, "example": 1 }, "cooldown_seconds": { "type": "integer", "minimum": 60, "maximum": 86400, "example": 60 } }, "required": [ "instance_size", "flock_size" ] } }, "required": [ "read_write", "read_scaling" ] } }, "required": [ "config" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "read_write": { "type": "object", "properties": { "instance_size": { "type": "string", "enum": [ "pulse", "standard", "jumbo", "mega", "giga" ], "example": "standard" }, "cooldown_seconds": { "type": "integer", "minimum": 60, "maximum": 86400, "example": 60 } }, "required": [ "instance_size" ] }, "read_scaling": { "type": "object", "properties": { "instance_size": { "type": "string", "enum": [ "pulse", "standard", "jumbo", "mega", "giga" ], "example": "standard" }, "flock_size": { "type": "number", "minimum": 0, "maximum": 64, "example": 1 }, "cooldown_seconds": { "type": "integer", "minimum": 60, "maximum": 86400, "example": 60 } }, "required": [ "instance_size", "flock_size" ] } }, "required": [ "read_write", "read_scaling" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.BAD_REQUEST" } } } }, "401": { "description": "Invalid Credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.UNAUTHORIZED" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.FORBIDDEN" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.NOT_FOUND" } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.INTERNAL_SERVER_ERROR" } } } } } } }, "/v1/active_accounts": { "get": { "operationId": "ducklings-getActiveAccounts", "summary": "Get active accounts", "description": "Get the active accounts in an organization, along with each account's running Ducklings (those in active or cooldown status). Requires 'Admin' role.", "tags": [ "accounts" ], "security": [ { "Authorization": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string" }, "ducklings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "\"rw\" or \"rs.N\" where N identifies which read scaling replica" }, "type": { "type": "string", "description": "\"read_write\" or \"read_scaling\"" }, "status": { "type": "string", "description": "\"active\" or \"cooldown\"" } }, "required": [ "id", "type", "status" ] } } }, "required": [ "username", "ducklings" ] } } }, "required": [ "accounts" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.BAD_REQUEST" } } } }, "401": { "description": "Invalid Credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.UNAUTHORIZED" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.FORBIDDEN" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.NOT_FOUND" } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.INTERNAL_SERVER_ERROR" } } } } } } }, "/v1/users": { "post": { "operationId": "users-createServiceAccount", "summary": "Create service account", "description": "Creates a service account with a 'Member' role. This endpoint does not create user accounts.", "tags": [ "users" ], "security": [ { "Authorization": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "allOf": [ { "type": "string", "pattern": "^[\\p{L}]", "minLength": 1, "maxLength": 255 }, { "type": "string", "pattern": "^[\\p{L}\\d_]*$" } ], "description": "username must be unique in an organization" } }, "required": [ "username" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string" } }, "required": [ "username" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.BAD_REQUEST" } } } }, "401": { "description": "Invalid Credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.UNAUTHORIZED" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.FORBIDDEN" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.NOT_FOUND" } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.INTERNAL_SERVER_ERROR" } } } } } } }, "/v1/users/{username}": { "delete": { "operationId": "users-delete", "summary": "Delete a user", "description": "Permanently delete a user and all of their data. THIS CANNOT BE UNDONE", "tags": [ "users" ], "security": [ { "Authorization": [] } ], "parameters": [ { "in": "path", "name": "username", "description": "user within the organization to delete", "schema": { "type": "string", "maxLength": 255, "description": "user within the organization to delete" }, "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string" } }, "required": [ "username" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.BAD_REQUEST" } } } }, "401": { "description": "Invalid Credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.UNAUTHORIZED" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.FORBIDDEN" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.NOT_FOUND" } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.INTERNAL_SERVER_ERROR" } } } } } } }, "/v1/users/{username}/tokens": { "post": { "operationId": "users-createToken", "summary": "Create an access token for a user", "tags": [ "tokens" ], "security": [ { "Authorization": [] } ], "parameters": [ { "in": "path", "name": "username", "description": "user within the organization", "schema": { "type": "string", "maxLength": 255, "description": "user within the organization" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ttl": { "type": "number", "minimum": 300, "maximum": 31536000, "description": "token expiration in seconds", "example": 3600 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "token_type": { "type": "string", "enum": [ "read_write", "read_scaling" ], "default": "read_write" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "access token" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "expire_at": { "type": "string", "description": "Time token expires at" }, "created_ts": { "type": "string", "description": "Time token was originally created" }, "read_only": { "type": "boolean" }, "token_type": { "type": "string", "enum": [ "read_write", "read_scaling" ] } }, "required": [ "token", "id", "created_ts", "read_only", "token_type" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.BAD_REQUEST" } } } }, "401": { "description": "Invalid Credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.UNAUTHORIZED" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.FORBIDDEN" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.NOT_FOUND" } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.INTERNAL_SERVER_ERROR" } } } } }, "description": "Creates an access token for a service account or for your own user account. Requires an Admin token when creating service account tokens." }, "get": { "operationId": "users-listTokens", "summary": "List a user's access tokens", "tags": [ "tokens" ], "security": [ { "Authorization": [] } ], "parameters": [ { "in": "path", "name": "username", "description": "user within the organization", "schema": { "type": "string", "maxLength": 255, "description": "user within the organization" }, "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "expire_at": { "type": "string", "description": "Time token expires at" }, "created_ts": { "type": "string", "description": "Time token was originally created" }, "read_only": { "type": "boolean" }, "token_type": { "type": "string", "enum": [ "read_write", "read_scaling" ] } }, "required": [ "id", "created_ts", "read_only", "token_type" ] } } }, "required": [ "tokens" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.BAD_REQUEST" } } } }, "401": { "description": "Invalid Credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.UNAUTHORIZED" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.FORBIDDEN" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.NOT_FOUND" } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.INTERNAL_SERVER_ERROR" } } } } }, "description": "Lists access token metadata for a service account or user account. Token secrets are not returned." } }, "/v1/users/{username}/tokens/{token_id}": { "delete": { "operationId": "users-deleteToken", "summary": "Invalidate a user access token", "tags": [ "tokens" ], "security": [ { "Authorization": [] } ], "parameters": [ { "in": "path", "name": "token_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "username", "description": "user within the organization", "schema": { "type": "string", "maxLength": 255, "description": "user within the organization" }, "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.BAD_REQUEST" } } } }, "401": { "description": "Invalid Credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.UNAUTHORIZED" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.FORBIDDEN" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.NOT_FOUND" } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.INTERNAL_SERVER_ERROR" } } } } }, "description": "Invalidates an access token for a service account or user account. Use the token ID, not the token secret." } }, "/v1/dives/{dive_id}/embed-session": { "post": { "operationId": "dashboards-createEmbedSession", "summary": "Create a Dive embed session for a service account", "description": "Creates an embed session for the specified Dive using a service account. The username must be a service account username, not a user account.", "tags": [ "dives" ], "security": [ { "Authorization": [] } ], "parameters": [ { "in": "path", "name": "dive_id", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "maxLength": 255, "description": "service account username within the organization to mint the embed session for" }, "session_name": { "type": "string", "minLength": 1, "description": "optional name used to reuse the same read-scaling session across embed requests" }, "required_resources": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1 }, "alias": { "type": "string" } }, "required": [ "url" ] }, "description": "Override the Dive's declared required resources for this embed session. When supplied, the Dive renders against this list in place of its source-declared REQUIRED_DATABASES." }, "initial_state": { "type": "object", "additionalProperties": {}, "description": "Seeds the embedded Dive's initial UI state. Each key is read by the corresponding `useDiveState` call inside the Dive." }, "version": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "description": "optional Dive version to use for the embed session" } }, "required": [ "username" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "string", "description": "opaque dive embed session" } }, "required": [ "session" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.BAD_REQUEST" } } } }, "401": { "description": "Invalid Credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.UNAUTHORIZED" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.FORBIDDEN" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.NOT_FOUND" } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.INTERNAL_SERVER_ERROR" } } } } } } } }, "components": { "securitySchemes": { "Authorization": { "type": "http", "scheme": "bearer" } }, "schemas": { "error.BAD_REQUEST": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message", "example": "Bad Request" }, "code": { "type": "string", "description": "The error code", "example": "BAD_REQUEST" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "description": "An array of issues that were responsible for the error", "example": [] } }, "required": [ "message", "code" ], "title": "Bad Request error (400)", "description": "The error information", "example": { "code": "BAD_REQUEST", "message": "Bad Request", "issues": [] } }, "error.UNAUTHORIZED": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message", "example": "Invalid Credentials" }, "code": { "type": "string", "description": "The error code", "example": "UNAUTHORIZED" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "description": "An array of issues that were responsible for the error", "example": [] } }, "required": [ "message", "code" ], "title": "Invalid Credentials error (401)", "description": "The error information", "example": { "code": "UNAUTHORIZED", "message": "Invalid Credentials", "issues": [] } }, "error.FORBIDDEN": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message", "example": "Unauthorized" }, "code": { "type": "string", "description": "The error code", "example": "FORBIDDEN" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "description": "An array of issues that were responsible for the error", "example": [] } }, "required": [ "message", "code" ], "title": "Unauthorized error (403)", "description": "The error information", "example": { "code": "FORBIDDEN", "message": "Unauthorized", "issues": [] } }, "error.NOT_FOUND": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message", "example": "Not Found" }, "code": { "type": "string", "description": "The error code", "example": "NOT_FOUND" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "description": "An array of issues that were responsible for the error", "example": [] } }, "required": [ "message", "code" ], "title": "Not Found error (404)", "description": "The error information", "example": { "code": "NOT_FOUND", "message": "Not Found", "issues": [] } }, "error.INTERNAL_SERVER_ERROR": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message", "example": "Internal Error" }, "code": { "type": "string", "description": "The error code", "example": "INTERNAL_SERVER_ERROR" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "description": "An array of issues that were responsible for the error", "example": [] } }, "required": [ "message", "code" ], "title": "Internal Error error (500)", "description": "The error information", "example": { "code": "INTERNAL_SERVER_ERROR", "message": "Internal Error", "issues": [] } } } } }