This page applies to Dash Enterprise 4.
The Dash Enterprise App Manager’s APIs provide access to the Dash Enterprise backend. Every action that you might perform when interacting with the App Manager UI is performed through the API.
The APIs that the App Manager uses are open and accessible to all Dash Enterprise users. Use these APIs to interact with the platform programmatically. For example, you can use the APIs to build CI/CD pipelines or report platform usage.
The Dash App Manager has two distinct APIs:
A REST User Management API to interact with the Admin’s User Management Panel. This is available at https://<your-dash-enterprise-server>/Auth/admin/user
. This is used to manage user accounts. This API is available for use but not yet documented. Inspect the network requests in the User Management Panel at https://<your-dash-enterprise-server>/Auth/admin/user to inspect the API requests. Authenticate to this API with your API key (see below).
A GraphQL API that’s used for all the remaining operations that aren’t specific to User Management, e.g. managing Dash Applications, Databases, Workspaces, Portal, SSH keys, and more. This API is documented in this chapter.
API Key
You will need an API Key for the Dash Enterprise account that will be making the API calls. To acquire an API key for an account, first login to the Dash Enterprise platform and click your username in the top right of the header bar and select “Manage API Key” from the dropdown.
Access Privileges
The API follows the known access privileges. For example if you are using an Admin account API key you will have the ability to access any application irrespective of the application owner. If you are using a non-admin account API key then you’ll be restricted to the apps that this account owns.
A GraphQL operation can either be a read or a write operation. A GraphQL query is used to read or fetch values while a mutation is used to write or post values.
GraphQL uses its own query language that allows you to specify just the data that you need.
Queries look like big, nested objects.
Note that the query is not JSON (it’s its own special syntax) but the response is JSON.
Here are a couple of examples:
View the first 10 apps
Query
query {
apps(page:0, allApps:true) {
apps {
name
urlOnServer
thumbnailUrl
hasWorkspace
}
}
}
Example Response
{
"data": {
"apps": {
"apps": [
{
"name": "aa-chris",
"urlOnServer": "https://<dash-enterprise>/aa-chris",
"thumbnailUrl": null,
"hasWorkspace": true
},
{
"name": "aa-chris-pipeline",
"urlOnServer": "https://<dash-enterprise>/aa-chris-pipeline",
"thumbnailUrl": null,
"hasWorkspace": true
},
{
"name": "aa-chris-timeouts-test",
"urlOnServer": "https://<dash-enterprise>/aa-chris-timeouts-test",
"thumbnailUrl": null,
"hasWorkspace": true
},
{
"name": "aa-hamza-test",
"urlOnServer": "https://<dash-enterprise>/aa-hamza-test",
"thumbnailUrl": null,
"hasWorkspace": true
},
{
"name": "aa-sf-template",
"urlOnServer": "https://<dash-enterprise>/aa-sf-template",
"thumbnailUrl": null,
"hasWorkspace": true
},
{
"name": "aa-tngo-checks",
"urlOnServer": "https://<dash-enterprise>/aa-tngo-checks",
"thumbnailUrl": null,
"hasWorkspace": true
},
{
"name": "aa-tngo-clinical-trial",
"urlOnServer": "https://<dash-enterprise>/aa-tngo-clinical-trial",
"thumbnailUrl": null,
"hasWorkspace": true
},
{
"name": "aa-tngo-conda",
"urlOnServer": "https://<dash-enterprise>/aa-tngo-conda",
"thumbnailUrl": null,
"hasWorkspace": true
},
{
"name": "aa-tngo-crm",
"urlOnServer": "https://<dash-enterprise>/aa-tngo-crm",
"thumbnailUrl": null,
"hasWorkspace": true
},
{
"name": "aa-tngo-databricks",
"urlOnServer": "https://<dash-enterprise>/aa-tngo-databricks",
"thumbnailUrl": null,
"hasWorkspace": false
}
]
}
}
}
Get all fields for a particular app
Note - We recommend that you don’t query the fields that you don’t need
rather than querying all of the fields. Certain fields will take
much longer to retrieve than other fields and so you can speed up
your queries by shortening them.
Query
query {
apps(name: "weekly-analytics", allApps: false) {
apps {
name
owner {
username
}
urlOnServer
thumbnailUrl
logs {
app
failed
}
collaborators {
users
teams
}
metadata {
title
description
tags
permissionLevel
showInPortal
sortRank
}
hasWorkspace
mounts {
hostDir
targetDir
status
}
processes {
type
number
status
}
analytics {
appname
}
environmentVariables {
name
value
status
readonly
}
linkedServices {
name
serviceType
created
status
}
status {
running
deploying
canScale
}
resources {
type
status
}
}
}
}
Note - This is a complete list of fields as of Dash Enterprise 4.0.1.
More fields may have been added in subsequent releases.
View the GraphiQL Playground (see below) to view the full list of fields.
Example Response
{
"data": {
"apps": {
"apps": [
{
"name": "weekly-analytics",
"owner": {
"username": "chriddyp"
},
"urlOnServer": "https://dash-playground.plotly.host/api",
"thumbnailUrl": null,
"logs": {
"app": "",
"failed": ""
},
"collaborators": {
"users": [],
"teams": []
},
"metadata": {
"title": null,
"description": null,
"tags": null,
"permissionLevel": "restricted",
"showInPortal": false,
"sortRank": null
},
"hasWorkspace": true,
"mounts": [],
"processes": [
{
"type": "web",
"number": 1,
"status": ""
}
],
"analytics": {
"appname": "api"
},
"environmentVariables": [],
"linkedServices": [],
"status": {
"running": false,
"deploying": false,
"canScale": true
},
"resources": []
}
]
}
}
}
Get the owner for a particular app
Query
query {
apps(name: "weekly-analytics", allApps: false) {
apps {
owner {
username
}
}
}
}
Example Response
{
"data": {
"apps": {
"apps": [
{
"owner": {
"username": "chriddyp"
}
}
]
}
}
}
View Which Apps Promoted to the Portal
Note Portal “name”. This is always “default”.
This field is not exposed in the UI nor configurable.
Query
query {
portals(page:0, name:"default") {
portals {
id
name
apps {
apps {
name
urlOnServer
thumbnailUrl
hasWorkspace
}
}
}
}
}
Example Response
{
"data": {
"portals": {
"portals": [
{
"id": 1,
"name": "default",
"apps": {
"apps": [
{
"name": "aa-chris",
"urlOnServer": "https://dash-playground.plotly.host/aa-chris",
"thumbnailUrl": null,
"hasWorkspace": true
},
{
"name": "api",
"urlOnServer": "https://dash-playground.plotly.host/api",
"thumbnailUrl": null,
"hasWorkspace": true
},
{
"name": "deck-explorer",
"urlOnServer": "https://dash-playground.plotly.host/deck-explorer",
"thumbnailUrl": null,
"hasWorkspace": false
}
]
}
}
]
}
}
}
The GraphQL API Playground is a built-in IDE to test and develop queries and mutations. It is shipped on Dash Enterprise and available at /Manager/graphql
.
You need to be logged in to Dash Enterprise to view the GraphQL API Playground.
The GraphQL API Playground comes with a built-in API reference for easier navigation. This reference contains the list of queries and mutations, with the ARGUMENTS
and TYPE
of each query and mutation.
The TYPE contains the list of fields that are returned in the response by the API.
Each type can be clicked on to show more information on it. There are standard types, e.g. String
, Boolean
, Int
, and Dash Enterprise specific types. These are lists of fields, e.g. Apps
, App
, Analytics
, Owner
.
This interface also comes with two important functionalities, autocompletion and error highlighting. In addition to the built-in reference, these should help when testing and writing queries and mutations.
The autocompletion feature does a typeahead search that finds possible keywords as you type your query. It also auto-fills the custom fields for nested objects when {}
is omitted.
Query example: For a given app, fetch the status, owner, CPU and memory usage.
query {
apps(name: "example", allApps: false) {
apps {
name
status {
running
}
owner {
username
}
analytics {
resources {
cpuUsage
memoryUsage
}
}
}
}
}
Mutation example: Create a new app named “my-dash-app”.
mutation {
addApp(name: "my-dash-app") {
error
app {
name
owner {
username
}
}
}
}
For the Python example, we’ll use the query from the sections above: For a given app, fetch the status, owner, CPU and memory usage.
In order to be able to send GraphQL requests to the API in Python, install the gql
package:
Import the necessary gql
classes:
from gql import Client, gql
from gql.transport.requests import RequestsHTTPTransport
Instantiate Client
object with the API url and your username and API key as the authentication credentials:
transport = RequestsHTTPTransport(
url="https://<your-dash-enterprise-server>/Manager/graphql",
auth=("admin", "your-api-key"),
use_json=True
)
client = Client(transport=transport)
Instantiate the gql
object with the query or mutation and execute it:
query = gql(
"""
query {
apps(name: "example", allApps: false) {
apps {
name
status {
running
}
owner {
username
}
analytics {
resources {
cpuUsage
memoryUsage
}
}
}
}
}
"""
)
result = client.execute(query)
print(result)
For the cURL example, we’ll use the mutation from the sections above: Create a new app named “my-dash-app”.
In a shell, using cURL, this mutation request can be made by executing the following command.
curl <a href="https://your-username:your-password@<your-dash-enterprise-server>/Manager/graphql">https://your-username:your-password@<your-dash-enterprise-server>/Manager/graphql</a> \
-H "Accept-Encoding: gzip, deflate, br" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Connection: keep-alive" \
-u your-username:your-api-key \
--data-binary '{"query":"mutation { addApp(name: "my-dash-app") { error app { name owner { username } } } }"}' \
--compressed
This should output:
{"data":{"addApp":{"error":null,"app":{"name":"my-dash-app","owner":{"username":"admin"}}}}}