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 beaviour is simpley preferable, job resource endpoints may provided for the operation. Created job resources can then be periodically polled to check the status of the operation. Such endpoits can be expected to contain a job qualifer. 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 qualifer. 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}.

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

The following are the Dash-specific URLs:

• https://login.brightdash.app/authorize
• https://login.brightdash.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

An audience parameter of https://assetplatform.io must be provided.

Please contact us to obtain your Client ID and Client Secret, and let us know which post-authorize redirect URLs we need to whitelist.

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 ADDED_BY criterion to find all Asset resources added 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.

Folders in a Dash account are represented by AttributeOptions, each of which belongs to the account's built-in Folders Attribute. The first step in getting all Folders for an account is to determine the attribute ID of the Folders Attribute, which can be done via the Folder Settings endpoint. The attribute ID of the Folders Attribute can then be used in an Attribute Option Search. It is recommended that you first search for top-level folders and then iterate through each of the folders to search for their sub-folders. The sample attribute option search requests show how to do this for a given attribute, you just need to substitute the attribute ID of your Folders Attribute.

Attribute resources define the custom metadata schema for Asset resources in your Dash account. Every Asset in your Dash account can be assigned a value or values for each Attribute you define.

The type and structure of the data stored against the Asset for each Attribute is described by a series of properties specified on the Attribute.

AttributeOption resources define the set of valid choices for an Attribute when Attribute.hasFixedOptions = true.

An AttributeOption has human-readable AttributeOption.value and an AttributeOption.position which determines the order in which it appears in relation to the other AttributeOption resources for an Attribute.

If Attribute.hierarchical = true then AttributeOption.parent is the AttributeOption which is the parent node of the AttributeOption in the tree. AttributeOption.position then determines the order in which the option appears in relation to the other options with the same AttributeOption.parent.

The AttributeOption resource intentionally does not include the list of child AttributeOption resources. This is to prevent costly loading of large AttributeOption tree structures. AttributeOption.leaf and AttributeOption.numberOfChildren properties can be used to determine the number of children for a node, but it is recomended to implement a combination of lazy-loading strategies using the GET Attribute Option and POST Asstribute Option Searches resources for retrieval.

e.g. Doing a GET Attribute Option with an AttributeOption.id value found in Asset.metadata.values will give the complete branch of the tree neccessary in the context of the viewing that Asset via the AttributeOption.parent property. For traversing down an AttributeOption tree POST Asstribute Option Searches can be used to first get all the top-level options and then each sub level as and when neeeded.

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

Criteria can be constructed based on direct comparison or pattern matching of a set of fixed AttributeOption properties.

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

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

AttributeViews provide an ordered view of a subset of Attributes, which can be configured by admins. This can be used to decide which Attributes to show alongside Assets in different contexts.

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 retrive all AssetFile resources for an Asset
• Asset.metadata which defines the assigned values for this Asset for Attribute resources
• A number of fixed properties, e.g. addedBy the User.id of whoever added the Asset

For the sake of permformance any Attribute and AttributeOption resources referenced in the Asset.metadata.values will need to be retrieved separately, if required.

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.

FThe AssetFile.id can be provided when creating an AssetDownload to downnload a specific AssetFile for an Asset.

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 Attribute resources where Attribute.hasFixedOptions = true a search using either the AttributeOption.id or AttributeOption.name will match.

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

e.g. Given the hierarchical AttributeOption structure Grandparent / Parent / Child, an Asset assigned the AttributeOption.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 mutliple 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.stagingStatus.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.

An AssetUpload resource is created when you want to upload a file to an Asset. Upon completion a new AssetFile is created will subsequently be returned in Asset.curentAssetFile. 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. The upload is then completed by sending a list of the eTags returned from each of these PUTs to AssetUploadComplete

An AssetDownload resource is created when you want to download and optionally transform an AssetFile of an Asset.

When ready a URL is provided to download the transformed file.

An AssetShare resource is a set of Assets which has been publicly shared for a limited period of time.

Dash provides a simple staging workflow for Asset resources to faciltate review and approval before they are accessible to other users. The staging workflow has three states

• STAGED
• PENDING_APPROVAL
• LIVE

Depending on the Asset.stagingStatus.state value an Asset reources will only be visble to certain users.

Asset resources begin in the STAGED state. While in the STAGED state Asset resources are only visble 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 visble to users where User.isAdmin = true.

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