Introduction

The Dash API follows the REST standard and uses common HTTP headers, methods and response codes. Request and response bodies are all in JSON format except for PUT requests of binary file data when upload files.

Operations, Jobs and Batches

If the standard PUT, PATCH and DELETE methods cannot adequately describe an operation on a resource the operation may itself be treated as a resource and the endpoint URLs will reflect this accordingly. For example making a POST to /asset-uploads returns an AssetUpload resource which describes the URL(s) the client should PUT the binary data to upload a file to an asset.

If an operation is unlikely to complete via a synchronous REST call, or asynchronous behaviour is simply preferable, job resource endpoints may provided for the operation. Created job resources can then be periodically polled to Get the status of the operation. Such endpoints can be expected to contain a job qualifier. e.g /asset-download-jobs and /asset-download-jobs/{id}

All job resources can be expected to conform to a polymorphic job structure with common properties such as id, progress and type specific properties such as dateCompleted for successfully completed jobs.

If an operation can be applied to multiple resources an endpoint may provided to create a batch resource for the operation. Such endpoints can be expected to contain a batch qualifier. As batch operations almost always need to be asynchronous you can expect to see both qualifiers in the endpoint URL e.g /asset-download-batch-jobs and /asset-download-batch-jobs/{id}.

Authorisation

Get a short-lived bearer token for testing

You should read the OAuth2 section if you want to set up programmatic API access to Dash. However, if you just want to try out an API endpoint, or want to request your client ID and secret (required for OAuth2 below), you can get a short-lived bearer token:

1. Log in to your Dash account as normal
2. Open the browser developer tools (CMD + OPTION + I on Mac or CTRL + SHIFT + I on Windows)
3. Click the "Application" tab
4. Under "Storage" in the left panel, expand "local storage"
5. Click on the URL of your Dash site
6. Copy the "value" for the access_token from the right-hand panel (be sure to select the whole thing - double click to edit, select all then copy).

This token can be used to try out an endpoint directly from these docs. Just click "Try it..." in the right-hand panel and enter your token in the "Auth" tab.

OAuth2

Dash uses OAuth 2.0 for authorisation. A good overview of OAuth 2.0 can be found here.

Endpoints:

• https://login.dash.app/authorize
• https://login.dash.app/oauth/token

Scopes to note:

• subdomain: this should be set to the subdomain of the Dash the user is trying to access e.g. subdomain:my-account
• offline_access: the standard OAuth 2.0 scope to use to obtain a refresh token

Audience: An query parameter of audience=https://assetplatform.io must be provided to the https://login.dash.app/authorize endpoint

To obtain your client ID and secret, follow the steps above to get a temporary bearer token and use this to create custom integration settings. The response you receive from the custom integrations settings endpoint will include your client ID and secret.

Authorization Code Flow

To begin the flow, send your user in a browser to to

https://login.dash.app/authorize?response_type=code&audience=https://assetplatform.io&client_id={YOUR_CLIENT_ID}&redirect_uri={YOUR_REDIRECT}&scope=offline_access%20subdomain:{YOUR_SUBDOMAIN}

Once the user successfully authenticates, they will be redirected to your redirect_uri with the Authorization Code provided in a query parameter.

Now that you have an Authorization Code, you must exchange it for your tokens via the https://login.dash.app/oauth/token endpoint

A more detailed description of the Authorization Code Flow can be found here

Authentication Without User Interaction

Due to security concerns, neither OAuth grant types Client Credentials or Password are supported by the Dash API.

If you require an automated script to call the Dash API, we recommend going through the Authorization Code Flow described above once, specifying the offline_access scope to get a refresh token along with your access token. Your script can store and use this refresh token to call https://login.dash.app/oauth/token and get a new access token when the current one expires.

Current User Details

The Bearer Token is a standard JWT token so can be useful to decode in some cases. For example, the sub field of the Bearer Token can be used in cases where you need access to the User.id of the current user.

e.g. When making an AssetSearch with the STAGED_BY criterion to find all Asset resources staged by the current user.

Alternatively the GET Current User endpoint contains properties for the current user to avoid needing to decode the Bearer Token.

Permitted Actions

In most responses from the Dash API you will find a permittedActions property alongside a result property which contains the resource. This is to provide context for operations the current user is permitted to perform on that resource.

If an expected permitted action is not included in the permittedActions property then the current user does not have permission to perform the action.

The GET Current User endpoint houses permitted actions which are not associated with a specific API resource instance. e.g. If the current user has permission to create new Asset resources then the GET Current User permittedActions property will contain the permitted action ASSETS : CREATE_ASSETS.

Common Use Cases

Getting fields and field options for asset metadata

Asset.metadata consists of a map of String to String[]

The keys for map are Field IDs. Full details, including the field name, can be got via the GET Field endpoint or the full list of fields for an account can be retrieved via the GET Fields endpoint.

The map values are a list of plain text values if Field.hasFixedOptions = false or a list of FieldOption IDs if Field.hasFixedOptions = true

Where Field.hasFixedOptions = true details, including the field option name, can be got via the GET Field Option endpoint.

Where Field.hierarchical = true the complete branch of the tree will be returned and can be constructed via the FieldOption.parent property.

Getting the full schema of fields and field options

The full list of fields for an account can be retrieved via the GET Fields endpoint.

Where Field.hasFixedOptions = true the POST Field Option Searches endpoint can be used to get the available options.

Where Field.hierarchical = true you should start with a PARENT_ID FIELD_IS_EMPTY query to get the top level options and then PARENT_ID FIELD_EQUALS queries to get each sub-level.

Folders

A Folder in Dash is simply a FieldOption, for the built-in Folders Field. To determine the ID of the Folders Field, use the Folder Settings endpoint. Once you have this ID, Folders behave the same as any other Field.

For getting the folder tree see Getting fields and field options for asset metadata and Getting the full schema of fields and field options

For getting assets in folders see AssetSearch

For getting assets in no folders see the Search for field is empty example in the POST Asset Searches endpoint.

Creating a new asset

Assets are the main resources in Dash. An asset consists of a file, some fixed properties (such as the date the asset was added to Dash) and custom metadata.

To create new assets and upload files:

1. Create an Asset and Upload batch job
2. Wait for the job to complete by checking the GET Asset and upload batch job endpoint
3. The completed job includes an AssetUpload resources in the job's result property. For each file you want to upload:
   • Make PUT requests to upload your file part with the byte ranges specified to the URLs in the corresponding AssetUploadPart.
   • Get the etag property from the response of each PUT request and use them to complete the upload via the (POST Asset Upload Completion)(#operation/postAssetUploadCompletion)
4. The assets will be created with a lifecycle status of STAGED. Use the POST Asset lifecycle transition batch job endpoint if you'd like to change the state of the assets (e.g. to PENDING_APPROVAL or LIVE).

Uploading a new file for an asset

1. Create an AssetUpload via the POST Asset Upload endpoint
2. Make PUT requests to upload your file part with the byte ranges specified to the URLs in the corresponding AssetUploadPart.
3. Get the etag property from the response of each PUT request and use them to complete the upload via the (POST Asset Upload Completion)(#operation/postAssetUploadCompletion)

Getting asset file versions

The current AssetFile for an Asset is returned in the Asset resource via the Asset.currentFile property.

The GET Asset Files endpoint can be used to get all AssetFile resources for an Asset

Editing asset metadata

Edit the contents of one or more Asset.metadata map properties via the POST Asset Metadata Edit Batch Job endpoint and check on the progress and status of the edit via the GET Asset Metadata Edit Batch Job endpoint.

Getting user collections

1. Get the current user ID from the current user details
2. Use this ID in the ASSOCIATED_WITH_USER criterion of the POST Collection Search endpoint to get all collections a user has access to.
3. To get the Asset resources in each collection see the All assets in a collection and Search within assets in a collection examples in the POST Asset Searches endpoint for how to specify the Collection.id in a COLLECTIONS : FIELD_EQUALS criterion.

Search by file extension

See the Search by file extension and Search by multiple file extensions example in the POST Asset Searches endpoint

Searching for changed assets

The following date properties exist on an asset and can be supplied as FIXED field criteria in the POST Asset Searches endpoint

• Asset.lifecycleStatus.dateStaged : The datetime the Asset was created but not yet live. DATE_STAGED in search criteria.
• Asset.lifecycleStatus.datePendingApproval : The datetime the Asset was set for approval (if it was). DATE_PENDING_APPROVAL in search criteria.
• Asset.lifecycleStatus.dateLive : The datetime the Asset was put live. DATE_LIVE in search criteria.
• Asset.currentAssetFile.dateAdded : The datetime the latest AssetFile was added. DATE_LAST_ASSET_FILE_ADDED in search criteria.
• Asset.dateLastModified : The datetime the any change was made to an Asset. This includes all of the above and any change to custom metadata DATE_LAST_MODIFIED in search criteria.

There is currently no way to determine if only custom metadata has changes.

Migration from V1

Several breaking changes have been introduced in the switch from V1 to V2, which are all the result of three changes.

• The domain is changing from brightdash.app to dash.app. All URLs used to access the API, including for authorisation, should be updated to the new domain.
• The concept of "asset staging status" has been renamed to "asset lifecycle" with the introduction of the bin, which adds another state for assets that isn't just about the staging workflow. This second change manifests in the changing of the StagingWorkflowTransitionBatchJob to the LifecycleTransitionBatchJob, a refactoring of the asset model to bring the "date added" and "added by" fields together with other lifecycle information, and the renaming of the "date added" and "added by" fields to the more specific "date live" and "staged by".
• Asset batch jobs used to only support carrying out operations on assets by a search criterion. This has been extended to also allow performing operations by id, so the "criterion" field has changed to a "selector" field which supports objects of either type.
• The term Attribute has been renamed to Field throughout, to mirror the change of terminology within the Dash frontend.

All these changes are described in more specific detail below.

Domain

• Domain has changed from brightdash.app to dash.app throughout the API.

Asset Staging Workflow

• The path of this endpoint has changed from asset-staging-workflow-transition-batch-jobs to asset-lifecycle-transition-batch-jobs.
• criterion in the POST body has become selector, and the criterion now needs to be wrapped in the following {"type": "BY_CRITERION", "criterion": {...}}.

Asset Searches

For both scroll and paged searches:

• The following criterion.field.fieldName and sorts.field.fieldName values have been renamed:
  • DATE_ADDED -> DATE_LIVE
  • ADDED_BY -> STAGED_BY
• The stagingStatus, addedBy, and dateAdded fields have been removed from the response. This data can now be found in the lifecycleStatus field.

Asset Deletion

• criterion in the POST body has become selector, and the criterion now needs to be wrapped in the following {"type": "BY_CRITERION", "criterion": {...}}.

Asset Metadata Edit

• criterion in the POST body has become selector, and the criterion now needs to be wrapped in the following {"type": "BY_CRITERION", "criterion": {...}}.

Search Filters

• The value returned from the searchField field of search filter results of type HARD_CODED_FREE_OPTION have changed from DATE_ADDED to DATE_LIVE. This isn't really a breaking change as the specification says this field could return any string, but it feels worth mentioning.

Saved Search

• The following criterion.field.fieldName and sorts.field.fieldName values have been renamed for both POSTing and GETting SavedSearches:
  • DATE_ADDED -> DATE_LIVE
  • ADDED_BY -> STAGED_BY

Attributes/Fields

• The string Attribute has been replaced with the string Field throughout. This includes e.g. AttributeOption being renamed to FieldOption. A simple find and replace should be enough to migrate.