Upserting Assets

Upsert assets

Create one or more assets

POSThttps://__tenant__.dscribedata.com/api/assets

Authorization

BearerAuth

Body

application/json

The filters passed to the request.

idstring

The ID of the asset to be created. If not provided, one will be generated for you. If provided, we will first try to update the asset before creating.

name*string

The name of the asset to be created.

discovery_policy_idstring

The id of the discovery policy of this asset. The discovery policy should already exist in the platform.

urlstring

A url pointing to the location of this specific asset in a source system.

descriptionstring

A description that will be shown on the asset in the dScribe platform.

asset_type*string

The id of the asset type. This equals a slugified version of the name. The asset type will have to exist in our system first. You can find the id on the Asset Type details page in the web application.

dsesarray of object

When creating a dataset, it is possible to immediately create dses. Just provide an array of dses as detailed in the dse docs. See an example here

propertiesarray of object

The property values to store on this asset. The property itself will have to be created in the platform first.

Response

200400500

Successful operation

Request

JavaScriptCurlPythonHTTP

const response = await fetch('https://__tenant__.dscribedata.com/api/assets', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify([
      {
        "name": "text",
        "asset_type": "text",
        "dses": [
          {
            "name": "text",
            "assets": [
              null
            ]
          }
        ],
        "properties": [
          {
            "property_id": "text",
            "value": [
              null
            ]
          }
        ]
      }
    ]),
});
const data = await response.json();

By default we will generate a unique asset ID for you, so you do not need to provide one. Should you wish to provide your own ID, you can do so by providing an ID property in the asset object. This could be helpful when updating assets, or tracking assets in your own system.

The above request will return a 200 status code if succesful. If one of the assets in the array failed to be created, none of the assets will have been stored.

You can upsert using the following code snippet:

const url = "https://{your_tenant}.dscribedata.com/api/assets";
const authToken = "yholmghj8§hbfg...";

fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${authToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify([
    {
      name: "Report 1",
      asset_type: "report",
      discovery_policy_id: "dp-id",
      url: "https://www.google.com",
      properties: [
        {
          property_id: "dfdh",
          value: ["value"],
        },
      ],
      source_properties: {
        "created_on": "2024-06-24T13:49:47.705Z",
        "created_by": "dScribe",
        "updated_on": "2024-06-24T13:49:47.705Z",
        "updated_by": "dScribe",
        "source_name": "Power BI",
        "source_type": "Report",
        "custom_fields": {
          "key_of_your_choice": "value"
        }
      },
      description: "This is a description",
    },
  ]),
)

The following details shows the proeprties you can send in the body in more detail:

Parameter	Required	Description
id	No	The ID of the asset to be created. If not provided, one will be generated for you. If provided, we will first try to update the asset before creating.
name	Yes	The name of the asset to be created.
discovery_policy_id	No	The id of the discovery policy of this asset. The discovery policy should already exist in the platform.
url	No	A url pointing to the location of this specific asset in a source system.
description	No	A description that will be shown on the asset in the dScribe platform.
asset_type	Yes	The id of the asset type. This equals a slugified version of the name. The asset type will have to exist in our system first. You can find the id on the Asset Type details page in the web application.
properties	No	The property values to store on this asset. The property itself will have to be created in the platform first.
source_properties	No	The source properties you want to store on the asset. In the custom_fields object, you can choose which key value pairs you want to set to the asset. These will be taken over and displayed in the app.
dses	No	When creating a dataset, it is possible to immediately create dses. Just provide an array of dses as detailed in the dse docs. See an example here

Examples: Create Datasets

Imagine you have a database somewhere that is not covered by one of our connectors. You can write a script that extracts the dataset metadata from your database, and then use the dScribe API to create those datasets in our platform.

Datasets are a special type of asset. In your request, you can immediatly specify some DSEs that will be linked to the dataset.

Look at the right for an example of how to create those datasets in our platform.

Examples: Adding Properties

To read more about properties, head over to our documentation.

For every asset you can add properties. Properties are extra metadata that you can configure to organize your assets and make the easier to find. To add properties to your assets you use the properties value in your request.

This is an array in the following shape:

[{
  property_id: "property_api_handle",
  value: ["property_value_api_handle"],
}]

To get the API handles you will first have to go the portal and navigate to the properties page in the admin panel. You can find the api handle here (click the icon to copy to clipboard):

properties api handle

The api handles of the values can be found once you click the pencil icon:

properties values api handle

Important note: If you are updating a multi select property, you have to provide a seperate object for every value you are trying to add like this:

[{
  property_id: "multi_select_api_handle",
  value: ["value_a"],
},
{
  property_id: "multi_select_api_handle",
  value: ["value_b"],
}]

Also note that the properties values will be overwritten. You have to provide all the values you would like to add in the request.

Examples: Adding Rich Text Properties

Within the dScribe platform, you have the possiblity to create Rich Text Input Properties.

To read more about properties, head over to our [documentation](https://documentation.dscribedata.com/configuration/custom-properties)

The simplest way to use them via the API is just providing some text. Behind the scenes we will wrap the text in a JSON structure like this:

[{
  type: 'paragraph',
  children: [{
    text: your_value_here
  }]
}]

If more convenient, you can also pass the above JSON value yourself. Using the JSON format gives you some extra possibilties, like creating a bulleted list complete with links. See a full example to the right.

This will result in the following:

bulleted list