{"openapi":"3.0.3","info":{"title":"MotherDuck REST API","version":"1.0.0"},"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 user. Requires 'Admin' role.","tags":["ducklings","instances"],"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"]},"cooldown_seconds":{"type":"integer","minimum":60,"maximum":86400}},"required":["instance_size"]},"read_scaling":{"type":"object","properties":{"instance_size":{"type":"string","enum":["pulse","standard","jumbo","mega","giga"]},"flock_size":{"type":"number","minimum":0,"maximum":64},"cooldown_seconds":{"type":"integer","minimum":60,"maximum":86400}},"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 user. Requires 'Admin' role","tags":["ducklings","instances"],"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"]},"cooldown_seconds":{"type":"integer","minimum":60,"maximum":86400}},"required":["instance_size"]},"read_scaling":{"type":"object","properties":{"instance_size":{"type":"string","enum":["pulse","standard","jumbo","mega","giga"]},"flock_size":{"type":"number","minimum":0,"maximum":64},"cooldown_seconds":{"type":"integer","minimum":60,"maximum":86400}},"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"]},"cooldown_seconds":{"type":"integer","minimum":60,"maximum":86400}},"required":["instance_size"]},"read_scaling":{"type":"object","properties":{"instance_size":{"type":"string","enum":["pulse","standard","jumbo","mega","giga"]},"flock_size":{"type":"number","minimum":0,"maximum":64},"cooldown_seconds":{"type":"integer","minimum":60,"maximum":86400}},"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":"[Preview] Get active accounts in an organization along with active Ducklings per account. 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 new user","description":"Create user is currently restricted to creating a user with a 'Member' role","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"},"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"}}}}}},"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"}}}}}}},"/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"}}}}}}},"/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.","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_hint":{"type":"string","minLength":1,"description":"optional hint 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":[]}}}}}