Fetching data

info

You will need to get a personal access token to use the search API.

The search API is used to fetch the right kind of data depending on your usage.

Getting started

Authentication

Here is a sample request around the search API, where we will fetch BUILDING_GROUPs and BUILDINGs.

You need to pass a query with something like that:

📄 search.sh

#!/bin/sh -ex

# Your organization
STONAL_ORG=DEMO

# Fetch your token from here: https://app.stonal.io/users/app
STONAL_TOKEN=9631e269-e21e-4ce6-92a9-c6f7ed1fa98a

curl \
  https://api.stonal.io/datalake/v1/organizations/$STONAL_ORG/assets/search \
  -v \
  -X POST \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $STONAL_TOKEN" \
  -d @query.json -o output.json

Initial query

📄 query.json

{
    "search": {
        "type": {
            "equals": [
                "BUILDING",
                "BUILDING_GROUP"
            ]
        }
    },
    "properties": {
      "simple": ["LAT", "LNG"]
    },
    "fields": [
        "name",
        "type",
        "uid",
        "externalIds"
    ],
    "paginate": {
        "size": 2
    }
}

The output will be similar to this:

📄 output.json

{
    "assets": [
        {
            "uid": "f6472f1a-9473-4fbf-9e1c-1c063eebb430",
            "name": "Building Group 1",
            "type": "BUILDING_GROUP",
            "externalIds": {
                "SOURCE_NAME": "BG001"
            },
            "properties": {
                "simple": {
                    "LAT": "46.800",
                    "LNG": "1.6959"
                }
            }
        },
        {
            "uid": "b81ce341-86f0-4cfe-a806-1d4a0f9a12ed",
            "name": "Building 1",
            "type": "BUILDING",
            "externalIds": {
                "SOURCE_NAME": "B001"
            },
            "properties": {
                "simple": {
                    "LAT": "46.500",
                    "LNG": "1.7959"
                }
            }
        }
    ],
    "paginate": {
        "size": 2,
        "cursor": "123456"
    }
}

Subsequent queries

Then to fetch the next batch of 10 assets, you shall issue the same query with the paginate.cursor set to the received value, ie "123456".

📄 query.json

{
    "search": {
        "type": {
            "equals": [
                "BUILDING",
                "BUILDING_GROUP"
            ]
        }
    },
    "fields": [
        "name",
        "type",
        "uid",
        "externalIds"
    ],
    "paginate": {
        "size": 2
        "cursor": "123456"
    }
}

The output will be similar to this:

📄 output.json

{
    "assets": [
        {
            "uid": "dd127caf-5b9b-4116-884e-b42505ac1bd6",
            "name": "Building Group 2",
            "type": "BUILDING_GROUP",
            "externalIds": {
                "CODE": "BG002"
            }
        },
        {
            "uid": "2c2ca7be-78f1-4734-a4c6-bbc773c9027b",
            "name": "Building 2",
            "type": "BUILDING",
            "externalIds": {
                "CODE": "B002"
            }
        }
    ],
    "paginate": {
        "size": 2,
        "cursor": "234567"
    }
}

Going further

There are many other ways to query data. And you can mix any of these filters.

Searching by external IDs

You can search using a single external ID, either from the asset itself or from its relations.

Searching a specific asset by one of its external IDs.

🔎 by asset's external ID

"search": {
    "asset": {
        "externalIds": {
          "SOURCE_NAME": "BG001"
        }  
    }
}

Searching assets whose parent matches the given external ID.

🔎 by the external ID of asset’s parent

"search": {
    "parent": {
        "externalIds": {
          "SOURCE_NAME": "BG001"
        }  
    }
}

Matching on a pattern

You can search for types matching a regex pattern.

Searching for spaces

note

SPACE is another name for rooms in the Stonal platform.

This will return assets of SPACE and SPACE|* types:

🔎 asset type pattern

"search": {
    "type": {
        "pattern": [
            "SPACE",
            "SPACE\\|.*"
        ]
    }
}

Please note that this will apply to all spaces within the organization. If you want to limit it to a particular building, you should combine it with a parent filter like this:

🔎 spaces within a specific building group

"search": {
    "type": {
        "pattern": [
            "SPACE",
            "SPACE\\|.*"
        ]
    },
    "parent": {
        "externalIds": {
            "SOURCE_NAME": "BG001"
        }
    }
}

Differential update

You can search data that has been updated since a particular date.

🔎 differential update

"search": {
    "updatedAtAfter":"2025-09-12T00:00:00"
}

Detect deleted assets

In search response, you can also include deleted assets matching specified filters.

🔎 detect deleted assets

"search": {
    "updatedAtAfter":"2025-09-12T00:00:00",
    "includeDeleted": true
}