API documentation
  • Getting started
  • Assets
    • Querying Assets
    • Upserting Assets
    • Deleting Assets
  • DSEs
    • Querying DSEs
    • Upserting DSEs
    • Deleting DSEs
  • Relations
    • Creating relations
    • Deleting relations
    • Supported node and relation types
  • API reference
Powered by GitBook
On this page
  1. Assets

Querying Assets

PreviousGetting startedNextUpserting Assets

Last updated 8 months ago

This page shows some examples on how to use the dScribe API to query assets.

Before you can query, you will first have to create some assets. Try our get inspired feature to quickly get some glossary items in your catalog!

Get assets

This endpoint will list your available assets. The query is paginated to the first 15 items. You can use the page and pageSize params to adjust this to your needs.

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

fetch(url, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${authToken}`,
    "Content-Type": "application/json",
  },
})

The response will look something like this.

Note the last page argument in the metadata object. We added it for your convenience to check if more assets need to be fetched.

{
  "metadata": {
    "page": 1,
    "pageSize": 20,
    "total": 3,
    "last_page": 1
  },
  "results": [
    {
      "id": "d3783f20-e6f7-4c20-9619-25d7cb04a232",
      "asset_type": {
        "id": "report",
        "name": "Report"
      },
      "properties": []
    },
    {
      "id": "0de2c3ed-e8b3-4be9-a782-fa74c239be47",
      "asset_type": {
        "id": "report",
        "name": "Report"
      },
      "properties": [
        {
          "value": ["d1f29d24-aa5d-4c83-b5d1-7dee4f0107a6"],
          "property_id": "2ed8351b-6f3e-444a-8c52-b9da82ad8b8a",
          "property_name": "Property 2",
          "component": "multi_select"
        }
      ]
    },
    {
      "id": "18917f91-1abc-4eb3-9b37-afa72ed742da",
      "asset_type": {
        "id": "dataset",
        "name": "Dataset"
      },
      "properties": [
        {
          "value": ["wajom"],
          "property_id": "3bb36a73-89d7-47ac-ac6a-8a3b19fd9005",
          "property_name": "Property 1",
          "component": "input"
        }
      ]
    }
  ]
}

Search assets

If you want a bit more control on the assets that are returned, you can use the search endpoint. You can do a fuzzy search on name or filter on any combination of asset types and other properties.

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

fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${authToken}`,
    "Content-Type": "application/json",
  },
  data: JSON.stringify({
    where: {
      name_contains: "finance",
      asset_type: ["dataset", "report"],
      properties: [
        {
          key: "05270b47-2175-4099-be82-077da5a28a35",
          operator: "equal",
          value: ["some value"]
        }
      ],
      source_properties: [
        {
          key: "WORKSPACE",
          operator: "equal",
          value: ["some value"]
        }
      ]
    },
  }),
});

Supported filters

filter
description

name_contains

Does a fuzzy search on the name field

asset_type

Only returns assets of the specified asset_types (e.g. dataset or report)

properties

List of properties to filter on, multiple ones will be combined as a logical AND

Properties

filter
description

key

The API handle of the property. You can find this in the property admin section of the web application

operator

One of the following: equal, not_equal, include, not_include, not_empty, empty, in (used for dates, you can filter on the last 7 days with the operator -7d/d)

value

The value of the property to filter on. For text properties, this is just a string. For selects, multi selects, collaborator and hierarchical selects this is the api handle that can be found in the web portal. For date properties, it is a range string, for example: -7d/d (last 7 days), -30d/d (last 30 days), ...

Find an asset

For some integrations it might be useful to only fetch one asset.

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

fetch(url, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${authToken}`,
    "Content-Type": "application/json",
  },
});

Query parameters

The following parameters can be added to all three requests:

addPropertyValueLabel boolean (default: false)

Add the label (and not only id) of property values returned on the asset. That would mean the properties array would go from:

{
    //...rest of the asset
    "properties": [{
        "value": ["2a94bc00-ef6a-4419-9a94-4ad072cf0d12"],
        "property_id": "44bc9716-6abb-4962-b4ca-081a1d6ef170__d11c886b-3e35-4f9c-961e-006f17ef8c54",
        "property_name": "Domain",
        "security_enabled": true,
        "component": "single_select"
    }]
}

to this:

{
    //...rest of the asset
    "properties": [{
        "value": [{
            "id": "2a94bc00-ef6a-4419-9a94-4ad072cf0d12",
            "label": "HR" // <-- notice the label
        }],
        "property_id": "44bc9716-6abb-4962-b4ca-081a1d6ef170__d11c886b-3e35-4f9c-961e-006f17ef8c54",
        "property_name": "Domain",
        "security_enabled": true,
        "component": "single_select"
    }]
}

addPropertyValueLabel boolean (default: false)

If true, the wysywig property value will be returned as full text instead of the the WYSYWIG JSON format (the JSON format includes mentions, links, images, etc...)

include boolean (default: false)

Adding include to the request will allow to add certain information that is not included by default. The only supported value at the moment is relations. Adding include=relations to get, find and search assets will include the relations to other assets or dses.

Find one specific asset

get

Get an asset based on the passed id

Authorizations
Path parameters
idstringRequired
Query parameters
addPropertyValueLabelbooleanOptional

Add the label (and not only id) of property values returned on the asset

Default: false
wysywigPropsAsFullTextbooleanOptional

If true, the wysywig property value will be returned as full text instead of the the WYSYWIG JSON format (the JSON format includes mentions, links, images, etc...)

Default: false
includestringOptional

A comma seperated list of objects to be included in the request. The only supported value is relations

Default: relations
Responses
200
Successful operation
application/json
500
Internal server error
get
GET /api/assets/{id} HTTP/1.1
Host: __tenant__.dscribedata.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "id": "text",
  "name": "text",
  "description": {
    "raw": "text",
    "text": "text"
  },
  "asset_type": {
    "id": "text",
    "name": "text"
  },
  "properties": [
    {
      "value": [
        "text"
      ],
      "property_id": "text",
      "property_name": "text",
      "component": "text"
    }
  ]
}
  • Get assets
  • GETList of existing assets
  • Search assets
  • POSTSearch through existing assets
  • Find an asset
  • GETFind one specific asset
  • Query parameters

Search through existing assets

post

Get a (paginated) list of the assets you have documented in dScribe based on the defined filters

Authorizations
Query parameters
pageinteger · int32 · min: 1Optional

Page from which to start returning results

Default: 1
pageSizeinteger · int32Optional

Number of results to return

Default: 15
addPropertyValueLabelbooleanOptional

Add the label (and not only id) of property values returned on the asset

Default: false
wysywigPropsAsFullTextbooleanOptional

If true, the wysywig property value will be returned as full text instead of the the WYSYWIG JSON format (the JSON format includes mentions, links, images, etc...)

Default: false
includestringOptional

A comma seperated list of objects to be included in the request. The only supported value is relations

Default: relations
Body
Responses
200
Successful operation
application/json
500
Internal server error
post
POST /api/assets/search HTTP/1.1
Host: __tenant__.dscribedata.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 54

{
  "where": {
    "asset_type": "text",
    "name_contains": "text"
  }
}
{
  "metadata": {
    "page": 1,
    "pageSize": 1,
    "total": 1,
    "last_page": 1
  },
  "results": [
    {
      "id": "text",
      "name": "text",
      "description": {
        "raw": "text",
        "text": "text"
      },
      "asset_type": {
        "id": "text",
        "name": "text"
      },
      "properties": [
        {
          "value": [
            "text"
          ],
          "property_id": "text",
          "property_name": "text",
          "component": "text"
        }
      ]
    }
  ]
}

List of existing assets

get

Get a (paginated) list of the assets you have documented in dScribe

Authorizations
Query parameters
pageinteger · int32 · min: 1Optional

Page from which to start returning results

Default: 1
pageSizeinteger · int32Optional

Number of results to return

Default: 15
addPropertyValueLabelbooleanOptional

Add the label (and not only id) of property values returned on the asset

Default: false
wysywigPropsAsFullTextbooleanOptional

If true, the wysywig property value will be returned as full text instead of the the WYSYWIG JSON format (the JSON format includes mentions, links, images, etc...)

Default: false
includestringOptional

A comma seperated list of objects to be included in the request. The only supported value is relations

Default: relations
Responses
200
Successful operation
application/json
500
Internal server error
get
GET /api/assets HTTP/1.1
Host: __tenant__.dscribedata.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "metadata": {
    "page": 1,
    "pageSize": 1,
    "total": 1,
    "last_page": 1
  },
  "results": [
    {
      "id": "text",
      "name": "text",
      "description": {
        "raw": "text",
        "text": "text"
      },
      "asset_type": {
        "id": "text",
        "name": "text"
      },
      "properties": [
        {
          "value": [
            "text"
          ],
          "property_id": "text",
          "property_name": "text",
          "component": "text"
        }
      ]
    }
  ]
}
Generating Glossary Items using Scribbles AI