Dash API (2.0.0)

Download OpenAPI specification:Download

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:

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

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

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

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.

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.

Accounts

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

Search for publicly available account data

Create a new PubliclyAvailableAccountData.

This endpoint is unauthenticated. Do not send a Bearer Token in the Authorization Header

Request Body schema: application/json
from
required
integer
Default: 0

The item number to begin the result set from

pageSize
required
integer
Default: 100

The maximum number of items to return in the result set

required
any (PubliclyAvailableAccountDataSearchCriterion)
sorts
required
Array of objects

This search does not accept any sorts, but has the sorts parameter anyway to fit in with other searches. You must always provide an empty list for this parameter.

Responses

Request samples

Content type
application/json
{
  • "from": 0,
  • "pageSize": 100,
  • "criterion": {
    },
  • "sorts": [ ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalResults": 15
}

Account Security

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

Auto-Tagging Image Settings

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

Folder Settings

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.

Get the account folder settings

Authorizations:

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/folder-settings \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Onboarding Checklist

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

Preset Transformations

Search for preset transformations

Create a new PresetTransformationSearch. This is most commonly used for finding presets that are applicable to a set of assets, so that one can be selected for use to create some AssetDownloads.

Authorizations:
Request Body schema: application/json
from
required
integer
Default: 0

The item number to begin the result set from

pageSize
required
integer
Default: 100

The maximum number of items to return in the result set

any (PresetTransformationSearchCriterion)
Array of objects (PresetTransformationSort)

Sorts to be applied to the search in order of precedence

Responses

Request samples

Content type
application/json
{
  • "from": 0,
  • "pageSize": 100,
  • "criterion": {
    },
  • "sorts": [ ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalResults": 2
}

Search Filters

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)

Get the account search filter view

Get the SearchFilter resources that have been configured as in use

Authorizations:

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/search-filter-view \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "accountId": "cfb665ca-ce35-4418-b9d5-70ee815db4bd",
  • "searchFilters": [
    ]
}

Subscription

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

Text In Image Settings

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

Theme

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

Search for account themes

Create a new ThemeSearch. This can be used to search for a theme by subdomain.

This endpoint is unauthenticated. Do not send a Bearer Token in the Authorization Header

Request Body schema: application/json
from
required
integer
Default: 0

The item number to begin the result set from

pageSize
required
integer
Default: 100

The maximum number of items to return in the result set

required
any (ThemeSearchCriterion)
sorts
required
Array of objects

This search does not accept any sorts, but has the sorts parameter anyway to fit in with other searches. You must always provide an empty list for this parameter.

Responses

Request samples

Content type
application/json
{
  • "from": 0,
  • "pageSize": 100,
  • "criterion": {
    },
  • "sorts": [ ]
}

Response samples

Content type
application/json
{}

Assets

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

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

Get an asset.

Get an Asset

Authorizations:
path Parameters
id
required
string

The unique ID of the Asset

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/assets/:id \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Delete an asset

Delete an Asset. All associated AssetFile resources will also be deleted.

Authorizations:
path Parameters
id
required
string

The unique ID of the Asset

Responses

Request samples

curl -i -X DELETE \
  https://api-v2.dash.app/assets/:id \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "timestamp": "2021-02-16T16:21:58.640+00:00",
  • "status": 401,
  • "error": "Unauthorized",
  • "message": null,
  • "path": "/folder-settings"
}

Create assets and upload files

An AssetAndUploadBatchJob should be created when you want to create multiple Asset resources and also create an AssetUpload for each of them.

Each asset can be uploaded in a single part or in multiple parts. If the filesize is less than 5MiB then it must be uploaded in a single part. If the filesize is greater than 5GiB then it must be uploaded in multiple parts, each smaller than 5GiB.

The AssetUpload resources in the completed job should then be used to upload the files for each and asset and complete each upload.

After the Asset resources have been created and files uploaded to them they will still be in Asset.lifecycleStatus.state = 'STAGED'. To send them for approval or put them live see Asset Lifecycle.

Authorizations:
Request Body schema: application/json
required
Array of objects (AssetAndUploadBatchRequestItem)

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "id": "be161977-d44e-4888-af3c-66522e223963",
  • "accountId": "cfb665ca-ce35-4418-b9d5-70ee815db4bd",
  • "creatorId": "google-oauth2|110955770826801837334",
  • "type": "IN_PROGRESS",
  • "progress": {
    },
  • "status": "PENDING"
}

Get the status of creating assets and uploading files

Get the status and eventual result of an AssetAndUploadBatchJob

Authorizations:
path Parameters
id
required
string

The unique ID of the AssetAndUploadBatchJob

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/asset-and-upload-batch-jobs/:id \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{}

Upload an asset file

Create a new AssetUpload resource for an existing Asset.

Authorizations:
Request Body schema: application/json
assetId
required
string

The ID of the Asset to create an AssetUpload for

assetFileId
string Nullable

The ID of the AssetFile to create am asset upload for. If null, a new AssetFile is created.

path
required
string

The path of the file including filename and any folders. This path will to set the value of the Asset Folder Field. Set to "/" to upload to the top-level in Dash.

size
required
integer

The size of the file that is to be uploaded (in bytes)

partSize
integer <= 5368709120 Nullable

Optionally specify the part size (in bytes) for multi-part uploading of the file. This must be less than 5368709120, and more than 5242880 unless it is the final part. If omitted or null a default part size will be used.

object (AssetUploadPartUrlsRequest)

Responses

Request samples

Content type
application/json
{
  • "assetId": "7af90a8b-7ccd-430f-a85d-e8614015bc47",
  • "assetFileId": "7af90a8b-7ccd-430f-a85d-e8614015bc47",
  • "path": "/Folder A/Folder D/a_file.jpg",
  • "size": 15318362,
  • "partSize": 7000000,
  • "partUrlsRequest": {
    }
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Complete an asset file upload

After an AssetUpload has been created and each part of the file data has been PUT to the relavant URL the eTag from each PUT must be sent to indicate the upload is complete.

Authorizations:
Request Body schema: application/json
assetId
string

The ID of the Asset the AssetUpload is for

uploadId
string

The unique identifier for the AssetUpload to this Asset

Array of objects (AssetUploadCompletedPart)

Responses

Request samples

Content type
application/json
{
  • "uploadId": "5a2481e0-819f-4b46-a7e6-143f943345f2",
  • "assetId": "7af90a8b-7ccd-430f-a85d-e8614015bc47",
  • "parts": [
    ]
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [ ]
}

Get an asset's files

Get all of the AssetFile resources for the specified Asset.

Authorizations:
path Parameters
id
required
string

The unique ID of the AssetFile

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/assets/:id/files \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
[]

Delete an asset file

Delete an AssetFile resource.

The Asset's current AssetFile cannot be deleted and will return an error if tried. (Only older version AssetFiles can be deleted.)

Authorizations:
path Parameters
id
required
string

The unique ID of the AssetFile

Responses

Request samples

curl -i -X DELETE \
  https://api-v2.dash.app/asset-files/:id \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "timestamp": "2021-02-16T16:21:58.640+00:00",
  • "status": 401,
  • "error": "Unauthorized",
  • "message": null,
  • "path": "/folder-settings"
}

Download assets

An AssetDownloadBatchJob should be created when you want to download and optionally transform multiple AssetFile resources.

You can optionally request that a zip is created of all the transformed files.

The transformationDescription in the request can be one of two types, CUSTOM or PRESET.

A CUSTOM transformationDescription is a list of candidateTransformations which are evaluated in turn against each AssetFile specified in the request. If the AssetFile meets the candidateTransformation.criteria then the candidateTransformation.transformation is applied. Otherwise, the next candiate is considered. The candidateTransformation.transformation is a series of operations to apply to the AssetFile in order (e.g. resize to 200 by 100 and then covert to JPG). An empty list of operations indicates the file should be left untransformed.

Putting this all together this allows you to describe a transformations such as:

  • Resized any image file, otherwise leave the file untransformed
  • Convert any image that supports transparency to PNG otherwise convert to JPG

A PRESET transformationDescription is similar to a CUSTOM transformation except the transformationDescription has been predefined. These presets are currently only configurable via the Dash frontend, but can be found via a PresetTransformationSearch.

Authorizations:
Request Body schema: application/json
required
Array of objects (AssetDownloadBatchRequestItem)
required
any (TransformationDescription)
zip
required
boolean

Whether to combine all the output files into a zip

Responses

Request samples

Content type
application/json
Example
{
  • "items": [
    ],
  • "transformationDescription": {
    },
  • "zip": true
}

Response samples

Content type
application/json
{
  • "id": "be161977-d44e-4888-af3c-66522e223963",
  • "accountId": "cfb665ca-ce35-4418-b9d5-70ee815db4bd",
  • "creatorId": "google-oauth2|110955770826801837334",
  • "type": "IN_PROGRESS",
  • "status": "PENDING",
  • "progress": {
    }
}

Get the status of downloading assets

Get the status and eventual result of an AssetDownloadBatchJob

Authorizations:
path Parameters
id
required
string

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/asset-download-batch-jobs/:id \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{}

Search for assets

A standard AssetSearch will only allow you to page to 10,000 results regardless of the value returned in the totalResults property.

If you need to be able to process more than 10,000 results consider an AssetScrollSearch instead.

Authorizations:
Request Body schema: application/json
from
required
integer
Default: 0

The item number to begin the result set from

pageSize
required
integer
Default: 100

The maximum number of items to return in the result set

required
any (AssetSearchCriterion)
required
Array of objects (AssetSort)

Sorts to be applied to the search in order of precedence

action
string
Default: "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.

Enum: "SEARCH_FOR_CHANGE_LIFECYCLE_STATE_TO_PENDING_APPROVAL" "SEARCH_FOR_CHANGE_LIFECYCLE_STATE_TO_LIVE" "SEARCH_FOR_CHANGE_LIFECYCLE_STATE_TO_BINNED" "SEARCH_FOR_DELETE" "SEARCH_FOR_EDIT" "SEARCH_FOR_PROMOTE_TO_LIVE" "SEARCH_FOR_SEND_FOR_APPROVAL" "SEARCH_FOR_VIEW"
object

A map of requested aggregations. The results will be returned in a map with the same provided keys.

Responses

Request samples

Content type
application/json
Example
{
  • "from": 0,
  • "pageSize": 100,
  • "criterion": {
    },
  • "sorts": [ ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalResults": 1337,
  • "aggregations": {
    }
}

Scroll search for assets

Asset scroll searches provide a means of scrolling one way through search results of any number of Asset resources.

Page size can stil be specified, but a scroll search will always proceed sequentially once through each page.

The AssetScrollSearch.scrollId in the search the response is used to continue the scroll search.

Authorizations:
Request Body schema: application/json
pageSize
integer
Default: 100

The maximum number of items to return in the result set

required
any (AssetSearchCriterion)
required
Array of objects (AssetSort)

Sorts to be applied to the search in order of precedence

action
string
Default: "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.

Enum: "SEARCH_FOR_CHANGE_LIFECYCLE_STATE_TO_PENDING_APPROVAL" "SEARCH_FOR_CHANGE_LIFECYCLE_STATE_TO_LIVE" "SEARCH_FOR_CHANGE_LIFECYCLE_STATE_TO_BINNED" "SEARCH_FOR_DELETE" "SEARCH_FOR_EDIT" "SEARCH_FOR_PROMOTE_TO_LIVE" "SEARCH_FOR_SEND_FOR_APPROVAL" "SEARCH_FOR_VIEW"

Responses

Request samples

Content type
application/json
{
  • "pageSize": 100,
  • "criterion": {
    },
  • "sorts": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalResults": 1337,
  • "scrollId": "58b0d88b-d0c9-47fc-9038-7195b234cc0b"
}

Continue an asset scroll search

Continue a previoulsy started AssetScrollSearch.

You must use the scrollId resturned in each new response as a scrollId is not guarenteed to remain fixed over the course of a scroll

Authorizations:
Request Body schema: application/json
scrollId
required
string

The ID to continue the AssetScrollSearch

Responses

Request samples

Content type
application/json
{
  • "scrollId": "58b0d88b-d0c9-47fc-9038-7195b234cc0b"
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalResults": 1337,
  • "scrollId": "58b0d88b-d0c9-47fc-9038-7195b234cc0b"
}

Update assets' metadata

Edit the metadata of a set of Assets by the specified assets selector.

Use the BY_IDS selector to edit a specific list of Asset.ids, or the BY_CRITERION selector to edit a search criterion, e.g. all Assets in a specific folder. See AssetSearch for more detail on the available criterion.

metadataFieldValueUpdates also has two types of objects that can be used. For example, a FieldOption with a value of "My Option" and an id of "3ba2cb5b-dbe9-48ed-8e07-71f26929e617" can be set either BY_VALUES by using the value "My Option", or BY_IDS by using the id "3ba2cb5b-dbe9-48ed-8e07-71f26929e617". For Fields that do not have FieldOptions (e.g. text fields), either type can be used.

Authorizations:
Request Body schema: application/json
any (AssetsSelector)
required
Array of any (MetadataFieldValueUpdate)

Responses

Request samples

Content type
application/json
{
  • "selector": {
    },
  • "metadataFieldValueUpdates": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "id": "be161977-d44e-4888-af3c-66522e223963",
  • "accountId": "cfb665ca-ce35-4418-b9d5-70ee815db4bd",
  • "creatorId": "google-oauth2|110955770826801837334",
  • "type": "IN_PROGRESS",
  • "status": "PENDING",
  • "progress": {
    }
}

Get the status of updating assets' metadata

Get the status of a Asset Metadata Edit Batch Job

Authorizations:
path Parameters
id
required
string

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/asset-metadata-edit-batch-jobs/:id \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
Example
{
  • "id": "be161977-d44e-4888-af3c-66522e223963",
  • "accountId": "cfb665ca-ce35-4418-b9d5-70ee815db4bd",
  • "creatorId": "google-oauth2|110955770826801837334",
  • "type": "IN_PROGRESS",
  • "status": "PENDING",
  • "progress": {
    }
}

Update assets' lifecycle stage

Move a set of Asset resources from one Asset.lifecycleStatus.state to another.

The Asset resources to be added to the batch job are specified using the AssetSearch criteria language or by a simple set of ids

If you are selecting by search criteria you must explicitly include criteria describing the state you are moving from in order to account for the fact that the Dash API will only return Assets in the 'LIVE' state by default. See the request examples for more.

Authorizations:
Request Body schema: application/json
any (AssetsSelector)
transition
string (LifecycleTransition)

The transition. Generally describe the state moving from and to.

Enum: "STAGED_TO_PENDING_APPROVAL" "STAGED_TO_LIVE" "PENDING_APPROVAL_TO_LIVE" "LIVE_TO_BINNED" "BINNED_TO_LIVE"

Responses

Request samples

Content type
application/json
Example
{
  • "transition": "STAGED_TO_PENDING_APPROVAL",
  • "selector": {
    }
}

Response samples

Content type
application/json
{
  • "id": "be161977-d44e-4888-af3c-66522e223963",
  • "accountId": "cfb665ca-ce35-4418-b9d5-70ee815db4bd",
  • "creatorId": "google-oauth2|110955770826801837334",
  • "type": "IN_PROGRESS",
  • "status": "PENDING",
  • "progress": {
    }
}

Get the status of updating assets' lifecycle stage

Get the status of an AssetLifecycleTransitionBatchJob

Authorizations:
path Parameters
id
required
string

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/asset-lifecycle-transition-batch-jobs/:id \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "id": "be161977-d44e-4888-af3c-66522e223963",
  • "accountId": "cfb665ca-ce35-4418-b9d5-70ee815db4bd",
  • "creatorId": "google-oauth2|110955770826801837334",
  • "type": "COMPLETED",
  • "progress": {
    },
  • "dateCompleted": "2021-02-15T09:24:01.417Z"
}

Asset Comments

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

Asset Deduplication

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

Create asset embeddable links

An AssetEmbeddableLinkBatchJob should be created when you want to create embeddable links for multiple AssetFile resources.

There is a limit of 500 batch request items for this endpoint. If more than 500 items are requested, the endpoint will error with a bad request(400) response.

The transformationDescription can be one of two types, CUSTOM or PRESET.

This definition and usage matches the transformationDescription used in AssetDownloadBatchJob.

A CUSTOM transformationDescription is a list of candidateTransformations which are evaluated in turn against each AssetFile specified in the request. If the AssetFile meets the candidateTransformation.criteria then the candidateTransformation.transformation is applied. Otherwise, the next candidate is considered. The candidateTransformation.transformation is a series of operations to apply to the AssetFile in order (e.g. resize to 200 by 100 and then covert to JPG). An empty list of operations indicates the file should be left untransformed.

A PRESET transformationDescription is similar to a CUSTOM transformation except the transformationDescription has been predefined. These presets are currently only configurable via the Dash frontend, but can be found via a PresetTransformationSearch.

Authorizations:
Request Body schema: application/json
required
Array of objects (EmbeddableLinkBatchRequestItem)
required
any (TransformationDescription)

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "transformationDescription": {
    }
}

Response samples

Content type
application/json
{
  • "id": "be161977-d44e-4888-af3c-66522e223963",
  • "accountId": "cfb665ca-ce35-4418-b9d5-70ee815db4bd",
  • "creatorId": "google-oauth2|110955770826801837334",
  • "type": "IN_PROGRESS",
  • "status": "PENDING",
  • "progress": {
    }
}

Get the status of creating asset embeddable links

Get the status and eventual result of an AssetEmbeddableLinkBatchJob

Authorizations:
path Parameters
id
required
string

The unique ID of the AssetEmbeddableLinkBatchJob

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/embeddable-link-batch-jobs/:id \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
Example
{
  • "id": "be161977-d44e-4888-af3c-66522e223963",
  • "accountId": "cfb665ca-ce35-4418-b9d5-70ee815db4bd",
  • "creatorId": "google-oauth2|110955770826801837334",
  • "type": "IN_PROGRESS",
  • "progress": {
    },
  • "status": "PENDING"
}

Search for asset embeddable links

Create a new AssetEmbeddableLinkSearch. The criterion and sort currently support search by ASSET_ID field only.

Authorizations:
Request Body schema: application/json
from
required
integer
Default: 0

The item number to begin the result set from

pageSize
required
integer
Default: 100

The maximum number of items to return in the result set

any (EmbeddableLinkSearchCriterion)
Array of objects (EmbeddableLinkSort)

Sorts to be applied to the search in order of precedence

Responses

Request samples

Content type
application/json
{
  • "from": 0,
  • "pageSize": 100,
  • "criterion": {
    },
  • "sorts": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalResults": 15
}

Asset Metadata Export

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

Asset Saved Crop Area Summaries

An Asset Saved Crop Area Summary resource is a saved crop area summary for a given AssetFile of an Asset.

Get an asset's saved crop area summaries

Get all of the SavedCropAreaSummaries resources for the specified Asset.

Authorizations:
path Parameters
id
required
string

The unique ID of the Asset

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/assets/:id/saved-crop-area-summaries \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
[
  • {
    }
]

Asset Saved Crop Areas

An Asset Saved Crop Area resource is a saved crop area for a given AssetFile of an Asset.

Create a saved crop area for an asset

Create a SavedCropArea for the specified Asset.

Authorizations:
path Parameters
id
required
string

The unique ID of the Asset

Request Body schema: application/json
presetId
required
string

The unique ID for a PresetTransformation. It only applies to CropTransformation presets.

required
object (CropParameters)
previewUri
required
string

The preview of this crop area in Base64

Responses

Request samples

Content type
application/json
{
  • "presetId": "string",
  • "cropParameters": {
    },
  • "previewUri": "string"
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Get a saved crop area

Get a SavedCropArea resource.

Authorizations:
path Parameters
id
required
string

The unique ID of the SavedCropArea

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/asset-saved-crop-areas/:id \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Update a saved crop area

Update a SavedCropArea resource. Only the provided fields will be updated

Authorizations:
path Parameters
id
required
string

The unique ID of the SavedCropArea

Request Body schema: application/json
object (CropParameters)
previewUri
string

The preview of this crop area in Base64

Responses

Request samples

Content type
application/json
{
  • "cropParameters": {
    },
  • "previewUri": "string"
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Delete a Saved Crop Area

Delete a SavedCropArea resource.

Authorizations:
path Parameters
id
required
string

The unique ID of the SavedCropArea

Responses

Request samples

curl -i -X DELETE \
  https://api-v2.dash.app/asset-saved-crop-areas/:id \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "timestamp": "2021-02-16T16:21:58.640+00:00",
  • "status": 401,
  • "error": "Unauthorized",
  • "message": null,
  • "path": "/folder-settings"
}

Asset Shares

An AssetShare resource is a set of Assets which has been publicly shared. This can be for a limited period of time or forever.

The assets shared can be view only or can also be downloaded.

Create an asset share

Create an AssetShare.

Authorizations:
Request Body schema: application/json
assetIds
required
Array of strings

The set of Asset identifiers that have been shared

expiry
required
string <date-time> Nullable

The datetime the share will expire and no longer be accessible in ISO datetime format. If the expiry is null, the share will never expire.

assetPermittedActions
string (AssetPermittedActionsWithDefault)
Default: "VIEW_AND_DOWNLOAD"

Permissions users have on assets they are viewing

Enum: "VIEW" "VIEW_AND_DOWNLOAD"

Responses

Request samples

Content type
application/json
{
  • "assetIds": [
    ],
  • "expiry": "2021-02-17T09:24:01.417Z",
  • "assetPermittedActions": "VIEW"
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Get an asset share

Get an AssetShare

This endpoint is unauthenticated. Do not send a Bearer Token in the Authorization Header

path Parameters
id
required
string

The unique ID of the AssetShare

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/asset-shares/:id

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Update an asset share

Patch an AssetShare

Authorizations:
path Parameters
id
required
string

The unique ID of the AssetShare

Request Body schema: application/json
object (NullableDateTimePatch)
assetPermittedActions
string (AssetPermittedActions)

Permissions users have on assets they are viewing

Enum: "VIEW" "VIEW_AND_DOWNLOAD"

Responses

Request samples

Content type
application/json
{
  • "expiry": {
    },
  • "assetPermittedActions": "VIEW"
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Delete an asset share

Delete an AssetShare resource.

Authorizations:
path Parameters
id
required
string

The unique ID of the AssetShare

Responses

Request samples

curl -i -X DELETE \
  https://api-v2.dash.app/asset-shares/:id \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "timestamp": "2021-02-16T16:21:58.640+00:00",
  • "status": 401,
  • "error": "Unauthorized",
  • "message": null,
  • "path": "/folder-settings"
}

Asset Share Access Tokens

Get an asset share access token

Get an access token for viewing data which has been shared as part of the AssetShare. Use this access token in the same way as the normal signed-in user token to make requests with the permissions of the share applied.

This endpoint is unauthenticated. Do not send a Bearer Token in the Authorization Header

path Parameters
id
required
string

The unique ID of the AssetShare

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/asset-shares/:id/access-token

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Asset Share Emails

Email a link to an asset share

Send an AssetShare via email to a specified email address

Authorizations:
Request Body schema: application/json
assetShareId
string

The unique ID for the AssetShare to be emailed

email
string

The email address to send the AssetShare to

Responses

Request samples

Content type
application/json
{
  • "assetShareId": "4517a7ba-a482-4211-b97e-f4256f53fd32",
  • "email": "john.smith@gmail.com"
}

Response samples

Content type
application/json
{
  • "timestamp": "2021-02-16T16:21:58.640+00:00",
  • "status": 401,
  • "error": "Unauthorized",
  • "message": null,
  • "path": "/folder-settings"
}

Collections

A Collection is a user defined set of Asset resources.

The Asset resources in a Collection are not returned with the Collection resource. To get the Asset resources you must create an Asset Search and use the Collection.id as the value in a COLLECTIONS : FIELD_EQUALS criterion.

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

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

Create a collection

Create a new Collection.

Authorizations:
Request Body schema: application/json
name
required
string

Name of the Collection

Responses

Request samples

Content type
application/json
{
  • "name": "Folders"
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Update a collection

Patch a Collection

Authorizations:
path Parameters
id
required
string

The unique ID of the Collection

Request Body schema: application/json
name
string Nullable

Name of the Collection

Responses

Request samples

Content type
application/json
{
  • "name": "Folders"
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Search for collections

Create a new CollectionSearch

The most commmon use of an CollectionSearch is to retrieve all the Collection resources associated with a User

Authorizations:
Request Body schema: application/json
from
required
integer
Default: 0

The item number to begin the result set from

pageSize
required
integer
Default: 100

The maximum number of items to return in the result set

any (CollectionSearchCriterion)
Array of objects (CollectionSort)

Sorts to be applied to the search in order of precedence

Responses

Request samples

Content type
application/json
{
  • "from": 0,
  • "pageSize": 100,
  • "criterion": {
    },
  • "sorts": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalResults": 3
}

Collection Shares

A CollectionShare is a Collection that has been made accessible to anyone with the id or slug of the Collection.

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

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

Create a collection share

Create a new CollectionShare, making a Collection available to anyone who has one of the CollectionShare.slugs.

Authorizations:
Request Body schema: application/json
collectionId
required
string

The unique ID of the Collection to be shared

expiry
string <date-time> Nullable
Default: null

The datetime the share will expire and no longer be accessible in ISO datetime format. If the expiry is null, the share will never expire.

assetPermittedActions
string (AssetPermittedActionsWithDefault)
Default: "VIEW_AND_DOWNLOAD"

Permissions users have on assets they are viewing

Enum: "VIEW" "VIEW_AND_DOWNLOAD"

Responses

Request samples

Content type
application/json
{
  • "collectionId": "a52b5315-15b8-417f-b742-d6902108bac1",
  • "expiry": "2021-02-17T09:24:01.417Z",
  • "assetPermittedActions": "VIEW"
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Get a collection share

Get a CollectionShare

This endpoint is unauthenticated. Do not send a Bearer Token in the Authorization Header

path Parameters
id
required
string

The unique ID of the CollectionShare

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/collection-shares/:id

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Update a collection share

Authorizations:
path Parameters
id
required
string

The unique ID of the CollectionShare

Request Body schema: application/json
object (NullableDateTimePatch)
assetPermittedActions
string (AssetPermittedActions)

Permissions users have on assets they are viewing

Enum: "VIEW" "VIEW_AND_DOWNLOAD"

Responses

Request samples

Content type
application/json
{
  • "expiry": {
    },
  • "assetPermittedActions": "VIEW"
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Delete a collection share

Delete a CollectionShare

Authorizations:
path Parameters
id
required
string

The unique ID of the CollectionShare

Responses

Request samples

curl -i -X DELETE \
  https://api-v2.dash.app/collection-shares/:id \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "timestamp": "2021-02-16T16:21:58.640+00:00",
  • "status": 401,
  • "error": "Unauthorized",
  • "message": null,
  • "path": "/folder-settings"
}

Search for publicly available collection shares

Create a new CollectionShareSearch

This endpoint is unauthenticated. Do not send a Bearer Token in the Authorization Header

Request Body schema: application/json
from
required
integer
Default: 0

The item number to begin the result set from

pageSize
required
integer
Default: 100

The maximum number of items to return in the result set

any (PublicCollectionShareSearchCriterion)
Array of objects (PublicCollectionShareSort)

Sorts to be applied to the search in order of precedence

Responses

Request samples

Content type
application/json
{
  • "from": 0,
  • "pageSize": 100,
  • "criterion": {
    },
  • "sorts": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalResults": 15
}

Cloud Connections

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

Cloud Import Jobs

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

Cloud Objects

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

Subdomains

A SubdomainAvailabilityCheck is used to check whether a Dash subdomain is in use or not.

Check subdomain availability

This endpoint is unauthenticated. Do not send a Bearer Token in the Authorization Header

Request Body schema: application/json
subdomain
string

The subdomain to check for availability

Responses

Request samples

Content type
application/json
{
  • "subdomain": "my-company"
}

Response samples

Content type
application/json
{
  • "subdomain": "my-company",
  • "isAvailable": true
}

Asset Download Events

An Asset Download Event Search allows you to search and aggregate over Asset Download Events

Criteria can be constructed based on exact or ranged comparison of the queryable event fields listed in the request schema below. Some fields like USER_TYPE and DOWNLOAD_TYPE have a fixed set of possible values which can be determined from the response scheme below.

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.

Only the ids of referenced resources such as Portal and Asset are provided in the response, which can then be used to GET the full resources.

Aggregations operations can also be performed on the events described by the criteria, in order to, for example

  • Search across all downloads and count the number of downloads for each asset
  • Search downloads for a specific user and count the number of downloads per month

Note, an Asset Download Event Search will only allow you to page to 10,000 but values returned in any aggregations and the totalResults property will be correct.

Search for asset download events

Authorizations:
Request Body schema: application/json
from
required
integer
Default: 0

The item number to begin the result set from

pageSize
required
integer
Default: 100

The maximum number of items to return in the result set

required
any (AssetDownloadEventSearchCriterion)
required
Array of objects (AssetDownloadEventSort)
Default: []

Sorts to be applied to the search in order of precedence

object

A map of requested aggregations. The results will be returned in a map with the same provided keys.

Responses

Request samples

Content type
application/json
Example
{
  • "from": 0,
  • "pageSize": 100,
  • "criterion": {
    },
  • "sorts": [
    ],
  • "aggregations": { }
}

Response samples

Content type
application/json
Example
{
  • "totalResults": 3,
  • "results": [
    ],
  • "aggregations": [ ]
}

Fields

Field 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 Field you define.

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

Get all fields

Get all Field resources ordered by Field.name.

Authorizations:

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/fields \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
[
  • {
    }
]

Get a field

Get a Field resource.

When Field.hasFixedOptions = true the FieldOption resources for this Field can be retrieved via an FieldOptionSearch

Authorizations:
path Parameters
id
required
string

The unique ID of the field

Example: cfb665ca-ce35-4418-b9d5-70ee815db4bd

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/fields/:id \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Update a field

Update a Field resource.

Authorizations:
path Parameters
id
required
string

The unique ID of the field

Example: cfb665ca-ce35-4418-b9d5-70ee815db4bd
Request Body schema: application/json
name
string Nullable

Human-readable name of the Field

recommended
boolean Nullable

If true it is recommended for assets to have a value for this Field. Clients should highlight missing recommended values during creation and editing of assets. Clients can also use the FIELD_IS_EMPTY criterion in an AssetSearch to find assets with missing recommended values.

object (NullableFieldOptionSearchFieldPatch)
browsable
boolean Nullable

Whether assets with a value for this Field can be browsed in the Browse page. Note that this option cannot be changed for Folder fields or non-fixed-option fields.

Responses

Request samples

Content type
application/json
{
  • "name": "Folders",
  • "recommended": true,
  • "defaultSortField": {
    },
  • "browsable": false
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Field Options

FieldOption resources define the set of valid choices for a Field when Field.hasFixedOptions = true.

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

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

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

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

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

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

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.

Create a field option

Create a new FieldOption resource adding it to the set of valid choices for an Field where Field.hasFixedOptions = true.

Authorizations:
Request Body schema: application/json
fieldId
required
string

The unique ID of the Field the FieldOption should belong to

value
required
string

The human-readable value of the FieldOption

position
required
integer

The 0-based position the FieldOption should occupy relative to the other options

parentId
string Nullable
Default: null

The FieldOption.id of the option above this one in the hierarchy

Responses

Request samples

Content type
application/json
Example
{
  • "fieldId": "a52b5315-15b8-417f-b742-d6902108bac1",
  • "value": "My Top Level Folder",
  • "position": 3,
  • "parentId": null
}

Response samples

Content type
application/json
Example
{
  • "result": {
    },
  • "permittedActions": [ ]
}

Get a field option

Get an FieldOption resource for an Field where Field.hasFixedOptions = true.

Authorizations:
path Parameters
id
required
string

The unique ID of the FieldOption

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/field-options/:id \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
Example
{
  • "result": {
    },
  • "permittedActions": [ ]
}

Delete a field option

Delete an FieldOption resource, removing it from the set of valid choices for an Field.

When deleting an option within a hierarchy of options all options in the hierarchy below the one being deleted will also be deleted.

Authorizations:
path Parameters
id
required
string

The unique ID of the FieldOption

Responses

Request samples

curl -i -X DELETE \
  https://api-v2.dash.app/field-options/:id \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "timestamp": "2021-02-16T16:21:58.640+00:00",
  • "status": 401,
  • "error": "Unauthorized",
  • "message": null,
  • "path": "/folder-settings"
}

Create field options

Create new FieldOption resources adding them to the set of valid choices for an Field where Field.hasFixedOptions = true.

Authorizations:
Request Body schema: application/json
required
Array of objects (FieldOptionBatchRequestItem)

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "successes": {
    },
  • "failures": {
    }
}

Search for field options

Create a new FieldOptionSearch

The most commmon uses of an FieldOptionSearch is to retrieve the FieldOption resources for an Field using the FIELD_ID field criterion. When Field.hierarchical = true it is recommended to retrieve each level of the tree via a separate search using PARENT_ID field criteria.

Authorizations:
Request Body schema: application/json
from
required
integer
Default: 0

The item number to begin the result set from

pageSize
required
integer
Default: 100

The maximum number of items to return in the result set

required
any (FieldOptionSearchCriterion)
required
Array of objects (FieldOptionSort)

Sorts to be applied to the search in order of precedence

Responses

Request samples

Content type
application/json
Example
{
  • "from": 0,
  • "pageSize": 100,
  • "criterion": {
    },
  • "sorts": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "results": [
    ],
  • "totalResults": 2
}

Field Option Images

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

Field Views

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

Get all field views

Get all FieldViews.

Authorizations:

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/field-views \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
[
  • {
    }
]

Guest Uploads

Guest Uploads allow guests to upload assets to a specific Folder.

Corebook

At present the Corebook integration with Dash is configured entirely within Corebook. However, Dash allows admins to set their CorebookSettings.corebookUrl, which will then show up as a "Brand" link to all users.

Get the account Corebook settings

Authorizations:

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/corebook-settings \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "result": {},
  • "permittedActions": [
    ]
}

Update the account Corebook settings

Authorizations:
Request Body schema: application/json
enabled
boolean

Whether Corebook integration is enable

corebookUrl
string

The URL to Corebook that will be used to link users to the brand guidelines

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "result": {},
  • "permittedActions": [
    ]
}

Custom

Get the account custom integration settings

Authorizations:

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/custom-integration-settings \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "result": {},
  • "permittedActions": [
    ]
}

Create or update the account custom integration settings

Authorizations:
Request Body schema: application/json
allowedWebOriginUrls
required
Array of strings

Allowed origins for use in the cross-origin authentication flow

allowedCallbackUrls
required
Array of strings

Allowed URLs for callback (i.e. with generated access token) during authentication flow

allowedLogoutUrls
required
Array of strings

Allowed URLs to redirect to after logout

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "result": {},
  • "permittedActions": [
    ]
}

Update the account custom integration settings

Authorizations:
Request Body schema: application/json
allowedWebOriginUrls
Array of strings Nullable

Allowed origins for use in the cross-origin authentication flow

allowedCallbackUrls
Array of strings Nullable

Allowed URLs for callback (i.e. with generated access token) during authentication flow

allowedLogoutUrls
Array of strings Nullable

Allowed URLs to redirect to after logout

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "result": {},
  • "permittedActions": [
    ]
}

Delete the account custom integration settings

Authorizations:

Responses

Request samples

curl -i -X DELETE \
  https://api-v2.dash.app/custom-integration-settings \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "timestamp": "2021-02-16T16:21:58.640+00:00",
  • "status": 401,
  • "error": "Unauthorized",
  • "message": null,
  • "path": "/folder-settings"
}

Shopify

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

Portals

Portals allow a public (or passcode protected) view on Assets within a set of folders.

Create a portal

Create a new Portal, allowing public access to specified folders to anyone who has one of the Portal.slugs.

Authorizations:
Request Body schema: application/json
name
required
string

Name of the Portal

slug
required
string

A human readable unique identifier, used in the Dash portal URL

whitelistedFolderFieldOptionIds
required
Array of strings

The folder FieldOptions which portal users will have permission to view/download assets from. Users will also have permission on the descendants of the specified field options.

required
object (WelcomeMessage)
showRecentlyAddedAssets
required
boolean

Whether this portal should include a preview of recently added assets

passcode
string Nullable

A passcode that must be provided when viewing a portal. Note that this is NOT a password and as such is stored in plain text

assetPermittedActions
string (AssetPermittedActionsWithDefault)
Default: "VIEW_AND_DOWNLOAD"

Permissions users have on assets they are viewing

Enum: "VIEW" "VIEW_AND_DOWNLOAD"

Responses

Request samples

Content type
application/json
{
  • "name": "Reseller portal",
  • "slug": "reseller-portal",
  • "whitelistedFolderFieldOptionIds": [
    ],
  • "welcomeMessage": {
    },
  • "showRecentlyAddedAssets": true,
  • "passcode": "LetMeInPlease",
  • "assetPermittedActions": "VIEW"
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Get a portal

Get a Portal

Authorizations:
path Parameters
id
required
string

The unique ID of the Portal

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/portals/:id \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Update a portal

Patch a Portal

Authorizations:
path Parameters
id
required
string

The unique ID of the Portal

Request Body schema: application/json
name
string Nullable

Name of the Portal

slug
string Nullable

A human readable unique identifier, used in the Dash portal URL

whitelistedFolderFieldOptionIds
Array of strings Nullable

The folder FieldOptions which portal users will have permission to view/download assets from.

object Nullable
showRecentlyAddedAssets
boolean Nullable

Whether this portal should include a preview of recently added assets

object (NullableStringFieldPatch)
assetPermittedActions
string (AssetPermittedActionsWithDefault)
Default: "VIEW_AND_DOWNLOAD"

Permissions users have on assets they are viewing

Enum: "VIEW" "VIEW_AND_DOWNLOAD"

Responses

Request samples

Content type
application/json
{
  • "name": "Reseller portal",
  • "slug": "reseller-portal",
  • "whitelistedFolderFieldOptionIds": [
    ],
  • "welcomeMessage": {
    },
  • "showRecentlyAddedAssets": true,
  • "passcode": {
    },
  • "assetPermittedActions": "VIEW"
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Delete a portal

Delete a Portal.

Authorizations:
path Parameters
id
required
string

The unique ID of the Portal

Responses

Request samples

curl -i -X DELETE \
  https://api-v2.dash.app/portals/:id \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "timestamp": "2021-02-16T16:21:58.640+00:00",
  • "status": 401,
  • "error": "Unauthorized",
  • "message": null,
  • "path": "/folder-settings"
}

Search for portals

Create a new PortalSearch

Authorizations:
Request Body schema: application/json
from
required
integer
Default: 0

The item number to begin the result set from

pageSize
required
integer
Default: 100

The maximum number of items to return in the result set

required
any (PortalSearchCriterion)
required
Array of objects (PortalSort)

Sorts to be applied to the search in order of precedence

Responses

Request samples

Content type
application/json
{
  • "from": 0,
  • "pageSize": 100,
  • "criterion": {
    },
  • "sorts": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalResults": 15
}

Portal Access Tokens

Get a portal access token

Get an access token for making requests as Portal user. Use this access token in the same way as the normal signed-in user token to make requests with the permissions of the share applied.

This endpoint is not authenticated with a Bearer token. Do not send a Bearer Token in the Authorization Header

If the portal has a passcode, select the portalPasscode Authorization header and prefix the passcode with "Passcode ".

Authorizations:
path Parameters
id
required
string

The unique ID of the Portal

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/portals/:id/access-token

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Portal Emails

Email a link to a portal

Send a Portal via email to a specified email address

Authorizations:
Request Body schema: application/json
portalId
string

The unique ID for the Portal to be emailed

email
string

The email address to send the Portal to

Responses

Request samples

Content type
application/json
{
  • "portalId": "55f9964c-095d-4b8b-bb5e-4118d2e76ad0",
  • "email": "john.smith@gmail.com"
}

Response samples

Content type
application/json
{
  • "timestamp": "2021-02-16T16:21:58.640+00:00",
  • "status": 401,
  • "error": "Unauthorized",
  • "message": null,
  • "path": "/folder-settings"
}

Saved Searches

A SavedSearch is an AssetSearch(#operation/postAssetSearch).criterion and AssetSearch(#operation/postAssetSearch).sorts that have been saved by a user. The user may also chose to receive email updates every time a new asset matches the saved criterion.

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

Create a saved search

Create a new SavedSearch resource.

Authorizations:
Request Body schema: application/json
name
required
string

Name of the SavedSearch

emailUserOnNewUploads
required
boolean

Whether to email the creator when a new upload matches the saved search criterion

required
any (AssetSearchCriterion)
required
Array of objects (AssetSort)

Sorts to be applied to the search in order of precedence

Responses

Request samples

Content type
application/json
{
  • "name": "My favourite search",
  • "emailUserOnNewUploads": true,
  • "criterion": {
    },
  • "sorts": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "1627573b-1273-441e-90d1-505d1f8ab47c",
  • "accountId": "cfb665ca-ce35-4418-b9d5-70ee815db4bd",
  • "creatorId": "google-oauth2|110955770826801837334",
  • "name": "My favourite search",
  • "emailUserOnNewUploads": true,
  • "criterion": {
    },
  • "sorts": [
    ]
}

Get a saved search

Get a SavedSearch resource.

Authorizations:
path Parameters
id
required
string

The unique ID of the SavedSearch

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/saved-searches/:id \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Update a saved search

Update a SavedSearch resource. Only the provided fields will be updated

Authorizations:
path Parameters
id
required
string

The unique ID of the SavedSearch

Request Body schema: application/json
name
string Nullable

Name of the SavedSearch

emailUserOnNewUploads
boolean Nullable

Whether to email the creator when a new upload matches the saved search criterion

Responses

Request samples

Content type
application/json
{
  • "name": "My favourite search",
  • "emailUserOnNewUploads": true
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Search for saved searches

Create a new SavedSearchSearch

The only use of a SavedSearchSearch as of now is to retrieve all the SavedSearch resources created by a User

Authorizations:
Request Body schema: application/json
from
required
integer
Default: 0

The item number to begin the result set from

pageSize
required
integer
Default: 100

The maximum number of items to return in the result set

required
any (SavedSearchSearchCriterion)
sorts
required
Array of objects

This search does not accept any sorts, but has the sorts parameter anyway to fit in with other searches. You must always provide an empty list for this parameter.

Responses

Request samples

Content type
application/json
{
  • "from": 0,
  • "pageSize": 100,
  • "criterion": {
    },
  • "sorts": [ ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalResults": 3
}

Groups

Groups are used to specify the permissions of Users in Dash.

Get all groups

Get all of the Groups in the current Account

Authorizations:

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/groups \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
[
  • {
    }
]

Staff Members

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

Users

The User resource contains information about a user in Dash such as their email address and their name (if provided).

Create a user

Create a new User in the current account

Authorizations:
Request Body schema: application/json
type
required
string
email
required
string

The email address of the User

welcomeMessage
string
Default: "You have been invited to join Dash — a tool for managing images, videos and more."

An optional welcome message included in the User user invite email

Responses

Request samples

Content type
application/json
Example
{
  • "type": "ADMIN",
  • "email": "john.smith@gmail.com",
  • "welcomeMessage": "You have been invited to join Dash — a tool for managing images, videos and more."
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Get a user

Get a User

Authorizations:
path Parameters
id
required
string

The unique ID of the User

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/users/:id \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

Get the current user

Get the currently authenticated User

Authorizations:

Responses

Request samples

curl -i -X GET \
  https://api-v2.dash.app/current-user \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "result": {
    },
  • "permittedActions": [
    ]
}

User Referrer

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

User Preferences

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