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.

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}.

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.

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.

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

curl --request POST \
  --url 'https://login.dash.app/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=authorization_code \
  --data 'client_id={YOUR_CLIENT_ID}' \
  --data 'client_secret={YOUR_CLIENT_SECRET}' \
  --data 'code={CODE_FROM_PREVIOUS_STEP}' \
  --data 'redirect_uri={YOUR_REDIRECT}'

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

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.

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.

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.

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.

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.

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.

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).

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)

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

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.

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.

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

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.

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 has changed from brightdash.app to dash.app throughout the API.

• 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": {...}}.

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.

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

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

• 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.

• 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

• 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.

Coming soon; contact us if you need access to this API endpoint.

Coming soon; contact us if you need access to this API endpoint.

Coming soon; contact us if you need access to this API endpoint.

Coming soon; contact us if you need access to this API endpoint.

For the most part Folders in Dash are just like any custom Field with Field.hasFixedOptions = true, Field.hierarchical = true and Field.multiValue = true.

The Folders Field also has the following behaviour.

• It cannot be deleted - Field.indestructable = true
• It is used to define Asset permissions for a UserGroup (currently only configurable via the Dash frontend, not via the API)
• A quick browse widget of your Folders Field appears on your Dash app homepage.

Folder Settings specify the Field.id of the Folders Field in your Dash.

Coming soon; contact us if you need access to this API endpoint.

The Search Filter View defines which filters appear, and the order in which they appear, in the left hand filter bar on the search page in the Dash frontend. These filters are used to build search criteria.

Filters either refer to a Field in your Dash or a one of a subset of the fixed search fields available in the search API (currently DATE_LIVE, FILE_TYPE or STAGED)

Coming soon; contact us if you need access to this API endpoint.

Coming soon; contact us if you need access to this API endpoint.

Coming soon; contact us if you need access to this API endpoint.

Coming soon; contact us if you need access to this API endpoint.

An Asset is the main resource in Dash. It consists of:

• One or more AssetFile resources, detailing the versions of a file for an Asset. Only the current AssetFile for an Asset is returned with the Asset resource. Use GET Asset Files to retrieve all AssetFile resources for an Asset
• Asset.metadata which defines the assigned values for this Asset for Field resources
• A number of fixed properties, e.g. addedBy the User.id of whoever added the Asset

For the sake of performance any Field and FieldOption resources referenced in the Asset.metadata.values will need to be retrieved separately, if required.

Searching

Searching allows you to find Asset resources in your Dash matching specific criteria.

Criteria can be constructed based on direct comparison or pattern matching of fields, where fields are either Asset.metadata.values or certain fixed Asset properties. The fixed KEYWORDS field can be used for a general purpose search as it will search across all Asset.metadata.values and fixed Asset properties.

For searches involving Field resources where Field.hasFixedOptions = true a search using either the FieldOption.id or FieldOption.name will match.

Any Asset which is assigned an FieldOption.id value for a Field resource where Field.hierarchical = true implicitly has the values of any parent FieldOption resources too. As such, any search using the parents FieldOption.id or FieldOption.name will match the Asset.

e.g. Given the hierarchical FieldOption structure Grandparent / Parent / Child, an Asset assigned the FieldOption.id of Child will also be returned in searches for Parent or Grandparent.

The logical operators AND, OR and NOT are provided to support complex queries based on multiple fields.

A list of sorts can also be provided to control the order in the which the results are returned.

The action property of a search, which defaults to SEARCH_FOR_VIEW, specifies the context in which the search is being run. For example if you only want to return Asset resources that the search User has permission to delete then set the action to be SEARCH_FOR_DELETE.

By default, searches will only returns results where Asset.lifecycleStatus.state = 'LIVE'. If you require search results to contain results with other state values, this needs to be explicitly included in the criteria.

Two kinds of search are possible, a standard AssetSearch and a AssetScrollSearch.`

Lifecycle

Dash provides a simple lifecycle for Asset resources to facilitate review and approval before they are accessible to other users, and also keep them BINNED after deletion so they can be retrieved. The lifecycle has four states

• STAGED
• PENDING_APPROVAL
• LIVE
• BINNED

Depending on the Asset.lifecycleStatus.state value an Asset resources will only be visible to certain users.

Asset resources begin in the STAGED state. While in the STAGED state Asset resources are only visible to the user who created the Asset and users where User.isAdmin = true.

A User with permission to create new Asset resources may not have the permission to move it to the LIVE state. While in the PENDING_APPROVAL state Asset resources are only visible to users where User.isAdmin = true.

Once in the LIVE state Asset resources visibility is defined by UserGroup permissions (currently only configurable via the Dash frontend, not via the API)

User can change the state of Assets to BINNED when the Asset is LIVE. A BINNED Asset can be restored to LIVE.

Asset Files

An AssetFile describes a version of a file for an Asset. Properties describe details of the file such as mediaType and dimensions (for images and videos). A previewUrl provides a means to access previews of the AssetFile

The current AssetFile for an Asset is returned with the Asset resource.

The AssetFile.id can be provided when creating an AssetDownload to download a specific AssetFile for an Asset.

An AssetUpload resource is created when you want to upload a file to an Asset. Upon completion a new AssetFile is created and will subsequently be returned in Asset.currentAssetFile. You can use GET Asset Files to retrieve the all AssetFile resources for an Asset.

The AssetUpload resource defines one or more URLs to which parts of the file should be PUT to.

Below is an example CURL PUT request that could be used to upload a local file part to an upload part URL taken from an AssetUpload:

curl --request PUT '<UPLOAD_PART_URL>' \
--header 'Content-Length: <SIZE_OF_PART>' \
--header 'Content-Type: <FILE_CONTENT_TYPE>' \
--data '@<PATH_TO_FILE_PART>'

The upload is then completed by sending a list of the eTags returned from each of these PUTs to AssetUploadComplete