App

View as Markdown

Get an appGET /api/2.0/apps/{name}List appsGET /api/2.0/appsCreate an appPOST /api/2.0/appsUpdate an appPATCH /api/2.0/apps/{name}Delete an appDELETE /api/2.0/apps/{name}Create an app updatePOST /api/2.0/apps/{app_name}/updateGet an app updateGET /api/2.0/apps/{app_name}/updateStart an appPOST /api/2.0/apps/{name}/startStop an appPOST /api/2.0/apps/{name}/stop

App object

namestring[ 2 .. 30 ] characters

The name of the app. The name must contain only lowercase alphanumeric characters and hyphens. It must be unique within the workspace.

Example: my-custom-app

descriptionstring<= 500 characters

The description of the app.

Example: My app description.

compute_statusobjectOutput only

Show child attributesHide child attributes

statestringOutput only

State of the app compute.

Values:

• COMPUTE_STATE_UNSPECIFIED
• ERROR
• DELETING
• STARTING
• STOPPING
• UPDATING
• STOPPED
• ACTIVE

messagestringOutput only

Compute status message

Example: App compute is active.

active_instancesint32GAOutput only

The number of active compute instances currently used and billed for this application.

app_statusobjectOutput only

Show child attributesHide child attributes

statestringOutput only

State of the application.

Values:

• APPLICATION_STATE_UNSPECIFIED
• DEPLOYING
• RUNNING
• CRASHED
• UNAVAILABLE

messagestringOutput only

Application status message

Example: Application is running.

running_instancesint32GAOutput only

The number of app instances whose application process is running.

urlstringOutput only

The URL of the app once it is deployed.

Example: my-custom-app-123.cloud.databricksapps.com

active_deploymentobjectOutput only

The active deployment of the app. A deployment is considered active when it has been deployed to the app compute.

Show child attributesHide child attributes

deployment_idstring

The unique id of the deployment.

Example: 01ef0bda89f21f08a8351f41e4a9b948

source_code_pathstring

The workspace file system path of the source code used to create the app deployment. This is different from deployment_artifacts.source_code_path, which is the path used by the deployed app. The former refers to the original source code location of the app in the workspace during deployment creation, whereas the latter provides a system generated stable snapshotted source code path used by the deployment.

Example: /Workspace/user@test.com/my_custom_app

git_sourceobjectGA

Git repository to use as the source for the app deployment.

Show child attributesHide child attributes

git_repositoryobjectOutput only

Git repository configuration. Populated from the app's git_repository configuration.

Show child attributesHide child attributes

urlstring<= 300 characters

URL of the Git repository.

Example: https://github.com/databricks/git_app_repo.git

providerstring

Git provider. Case insensitive. Supported values: gitHub, gitHubEnterprise, bitbucketCloud, bitbucketServer, azureDevOpsServices, gitLab, gitLabEnterpriseEdition, awsCodeCommit.

Example: gitHub

auto_deploybooleanGA

When true, automatically deploys the app on push events to the branch configured in the app's deployment_source.git_source.

caller_credential_idint64GAInput only

ID of a personal access token Git credential owned by the caller, used to grant the app's service principal access to this repository.

Example: 93488329053511

branchstring<= 255 characters

Git branch to checkout.

Example: main

tagstring<= 255 characters

Git tag to checkout.

Example: v1.0.0

commitstring<= 64 characters

Git commit SHA to checkout.

Example: abc123def456

source_code_pathstring<= 500 characters

Relative path to the app source code within the Git repository. If not specified, the root of the repository is used.

Example: my-app

resolved_commitstring<= 64 charactersGAOutput only

The resolved commit SHA that was actually used for the deployment. This is populated by the system after resolving the reference (branch, tag, or commit). If commit is specified directly, this will match commit. If a branch or tag is specified, this contains the commit SHA that the branch or tag pointed to at deployment time.

Example: abc123def456789012345678901234567890abcd

modestring

The mode of which the deployment will manage the source code.

Values:

• MODE_UNSPECIFIED
• SNAPSHOT
• AUTO_SYNC

deployment_artifactsobjectOutput only

The deployment artifacts for an app.

Show child attributesHide child attributes

source_code_pathstring

The snapshotted workspace file system path of the source code loaded by the deployed app.

Example: /Workspace/Users/9627a015-e892-43f7-9085-eec3892da408/src/01ef1a1ed75d1964b62234a35efa61fc

statusobjectOutput only

Status and status message of the deployment

Show child attributesHide child attributes

statestringOutput only

State of the deployment.

Values:

• STATE_UNSPECIFIED
• SUCCEEDED
• FAILED
• IN_PROGRESS
• CANCELLED

messagestringOutput only

Message corresponding with the deployment state.

Example: Deployment is in progress.

create_timestringOutput only

The creation time of the deployment. Formatted timestamp in ISO 6801.

creatorstringOutput only

The email of the user creates the deployment.

Example: user@test.com

update_timestringOutput only

The update time of the deployment. Formatted timestamp in ISO 6801.

commandarray of stringGA

The command with which to run the app. This will override the command specified in the app.yaml file.

Example: python app.py

env_varsarray of objectGA

The environment variables to set in the app runtime environment. This will override the environment variables specified in the app.yaml file.

Show child attributesHide child attributes

namestringGA

The name of the environment variable.

Example: VOLUME_URI

valuestringGA

The value for the environment variable.

Example: /Volumes/catalog-name/schema-name/dir-name

value_fromstringGA

The name of an external <Databricks> resource that contains the value, such as a secret or a database table.

Example: volume

create_timestringOutput only

The creation time of the app. Formatted timestamp in ISO 6801.

creatorstringOutput only

The email of the user that created the app.

Example: user@test.com

update_timestringOutput only

The update time of the app. Formatted timestamp in ISO 6801.

updaterstringOutput only

The email of the user that last updated the app.

Example: user@test.com

pending_deploymentobjectOutput only

The pending deployment of the app. A deployment is considered pending when it is being prepared for deployment to the app compute.

Show child attributesHide child attributes

deployment_idstring

The unique id of the deployment.

Example: 01ef0bda89f21f08a8351f41e4a9b948

source_code_pathstring

The workspace file system path of the source code used to create the app deployment. This is different from deployment_artifacts.source_code_path, which is the path used by the deployed app. The former refers to the original source code location of the app in the workspace during deployment creation, whereas the latter provides a system generated stable snapshotted source code path used by the deployment.

Example: /Workspace/user@test.com/my_custom_app

git_sourceobjectGA

Git repository to use as the source for the app deployment.

Show child attributesHide child attributes

git_repositoryobjectOutput only

Git repository configuration. Populated from the app's git_repository configuration.

Show child attributesHide child attributes

urlstring<= 300 characters

URL of the Git repository.

Example: https://github.com/databricks/git_app_repo.git

providerstring

Git provider. Case insensitive. Supported values: gitHub, gitHubEnterprise, bitbucketCloud, bitbucketServer, azureDevOpsServices, gitLab, gitLabEnterpriseEdition, awsCodeCommit.

Example: gitHub

auto_deploybooleanGA

When true, automatically deploys the app on push events to the branch configured in the app's deployment_source.git_source.

caller_credential_idint64GAInput only

ID of a personal access token Git credential owned by the caller, used to grant the app's service principal access to this repository.

Example: 93488329053511

branchstring<= 255 characters

Git branch to checkout.

Example: main

tagstring<= 255 characters

Git tag to checkout.

Example: v1.0.0

commitstring<= 64 characters

Git commit SHA to checkout.

Example: abc123def456

source_code_pathstring<= 500 characters

Relative path to the app source code within the Git repository. If not specified, the root of the repository is used.

Example: my-app

resolved_commitstring<= 64 charactersGAOutput only

The resolved commit SHA that was actually used for the deployment. This is populated by the system after resolving the reference (branch, tag, or commit). If commit is specified directly, this will match commit. If a branch or tag is specified, this contains the commit SHA that the branch or tag pointed to at deployment time.

Example: abc123def456789012345678901234567890abcd

modestring

The mode of which the deployment will manage the source code.

Values:

• MODE_UNSPECIFIED
• SNAPSHOT
• AUTO_SYNC

deployment_artifactsobjectOutput only

The deployment artifacts for an app.

Show child attributesHide child attributes

source_code_pathstring

The snapshotted workspace file system path of the source code loaded by the deployed app.

Example: /Workspace/Users/9627a015-e892-43f7-9085-eec3892da408/src/01ef1a1ed75d1964b62234a35efa61fc

statusobjectOutput only

Status and status message of the deployment

Show child attributesHide child attributes

statestringOutput only

State of the deployment.

Values:

• STATE_UNSPECIFIED
• SUCCEEDED
• FAILED
• IN_PROGRESS
• CANCELLED

messagestringOutput only

Message corresponding with the deployment state.

Example: Deployment is in progress.

create_timestringOutput only

The creation time of the deployment. Formatted timestamp in ISO 6801.

creatorstringOutput only

The email of the user creates the deployment.

Example: user@test.com

update_timestringOutput only

The update time of the deployment. Formatted timestamp in ISO 6801.

commandarray of stringGA

The command with which to run the app. This will override the command specified in the app.yaml file.

Example: python app.py

env_varsarray of objectGA

The environment variables to set in the app runtime environment. This will override the environment variables specified in the app.yaml file.

Show child attributesHide child attributes

namestringGA

The name of the environment variable.

Example: VOLUME_URI

valuestringGA

The value for the environment variable.

Example: /Volumes/catalog-name/schema-name/dir-name

value_fromstringGA

The name of an external <Databricks> resource that contains the value, such as a secret or a database table.

Example: volume

resourcesarray of object

Resources for the app.

Show child attributesHide child attributes

namestring[ 2 .. 30 ] characters

Name of the App Resource.

Example: api-key

descriptionstring<= 50 characters

Description of the App Resource.

Example: API key for external service.

secretobject

Show child attributesHide child attributes

scopestring

Scope of the secret to grant permission on.

Example: my-scope

keystring

Key of the secret to grant permission on.

Example: my-key

permissionstring

Permission to grant on the secret scope. For secrets, only one permission is allowed. Permission must be one of: "READ", "WRITE", "MANAGE".

Values:

• READ
• WRITE
• MANAGE

Example: READ

sql_warehouseobject

Show child attributesHide child attributes

idstring

Id of the SQL warehouse to grant permission on.

Example: e9ca293f79a74b5c

permissionstring

Permission to grant on the SQL warehouse. Supported permissions are: "CAN_MANAGE", "CAN_USE", "IS_OWNER".

Values:

• CAN_MANAGE
• CAN_USE
• IS_OWNER

Example: CAN_USE

serving_endpointobject

Show child attributesHide child attributes

namestring

Name of the serving endpoint to grant permission on.

Example: databricks-meta-llama-3-1-70b-instruct

permissionstring

Permission to grant on the serving endpoint. Supported permissions are: "CAN_MANAGE", "CAN_QUERY", "CAN_VIEW".

Values:

• CAN_MANAGE
• CAN_QUERY
• CAN_VIEW

Example: CAN_QUERY

jobobject

Show child attributesHide child attributes

idstring

Id of the job to grant permission on.

Example: 1234

permissionstring

Permissions to grant on the Job. Supported permissions are: "CAN_MANAGE", "IS_OWNER", "CAN_MANAGE_RUN", "CAN_VIEW".

Values:

• CAN_MANAGE
• IS_OWNER
• CAN_MANAGE_RUN
• CAN_VIEW

Example: CAN_VIEW

uc_securableobject

Show child attributesHide child attributes

securable_full_namestring

Example: my-catalog.my-schema.my-volume

securable_typestring

Values:

• VOLUME
• TABLE
• FUNCTION
• CONNECTION

Example: VOLUME

permissionstring

Values:

• READ_VOLUME
• WRITE_VOLUME
• SELECT
• EXECUTE
• USE_CONNECTION
• MODIFY

securable_kindstringGAOutput only

The securable kind from Unity Catalog. See https://docs.databricks.com/api/workspace/tables/get#securable_kind_manifest-securable_kind.

databaseobject

Show child attributesHide child attributes

instance_namestring

Example: my-database-instance

database_namestring

Example: my-database

permissionstring

Values:

• CAN_CONNECT_AND_CREATE

Example: CAN_CONNECT_AND_CREATE

genie_spaceobject

Show child attributesHide child attributes

namestring

Example: my-genie-space

space_idstring

Example: 550e8400-e29b-41d4-a716-446655440000

permissionstring

Values:

• CAN_MANAGE
• CAN_EDIT
• CAN_RUN
• CAN_VIEW

Example: CAN_MANAGE

experimentobject

Show child attributesHide child attributes

experiment_idstring

Example: 1021971371025173

permissionstring

Values:

• CAN_MANAGE
• CAN_EDIT
• CAN_READ

Example: CAN_MANAGE

appobjectGA

Show child attributesHide child attributes

namestringGA

Example: my-app

permissionstringGA

Values:

• CAN_USE

Example: CAN_USE

postgresobjectGA

Show child attributesHide child attributes

branchstringGA

Example: projects/proj-abc123/branches/branch-xyz789

databasestringGA

Example: projects/proj-abc123/branches/branch-xyz789/databases/db-456

permissionstringGA

Values:

• CAN_CONNECT_AND_CREATE

Example: CAN_CONNECT_AND_CREATE

service_principal_idint64Output only

service_principal_namestringOutput only