---
title: "ServitlyClient"
slug: "servitly-api-client"
updated: 2025-10-20T19:41:32Z
published: 2025-10-20T19:41:32Z
canonical: "learn.servitly.com/servitly-api-client"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://learn.servitly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ServitlyClient

To interact with the [Servitly backend API](/apidocs), you can leverage the `ServitlyClient`, which is available in the JavaScript context under the variable `servitlyClient`. It provides methods to retrieve, create, update, and delete data related to customers, locations, things, metrics, and more.

```javascript
servitlyClient.getMeThings({}, function(things){
   // do stuff with the retreived things
}, function(error){
   console.error("Error retrieving things", error);
});
```

#### Filter Parameter

All methods accessing collections of objects, e.g. `getMeThings(filter,....)`, requires a parameter that is used to pass the conditions for filtering the requested objects. Filter is a JSON object that can contain any of the following fields:

- *thingId*: the identifier of the thing.
- *locationId*: the identifier of the location.
- *customerId*: the identifier of the customer.
- *parentThingId*: the identifier of the parent thing.
- *query*: the array of property-based conditions. `[{"property": "name", "predicate": "eq", "value": "test"}, {...}]` PREDICATES beginsWith, eq, neq, gt, gte, lt, lte, like, notLike, isEmpty, isNotEmpty.
- *limit*: the maximum number of elements to retrieve.
- *startDate*: the start date in milliseconds used to filter result elements by creation timestamp.
- *endDate*: the end date in milliseconds used to filter result elements by creation timestamp.
- *aggregation*: the aggregation function and time frame to retrieve aggregated metric values (e.g., AVG_DAY_1).

Here is an example of the parameter named `filter` to retrieve things for a customer.

```json
{
	"customerId": "1234567",
	"query": [
		{
			"property": "name",
			"predicate": "like",
			"value": "*XYZ*"
		}
	]
}
```

#### Callback Parameters

- *success*: the callback that is called when the method successfully completes. This function receives the response object (e.g., thing JSON).
- *error*: the callback that is called when the method invocation fails. This function receives the error details object.

In case you are using the `ServitlyClient` into a Promise, you can directly pass the *resolve* and *reject* callbacks.

```javascript
new Promise(function (resolve, reject) {
     servitlyClient.getMeThings({}, resolve, reject); 
});
```

## General Methods

With the following methods, you can invoke any of the [Servitly backend API](/apidocs).

| *doGet(endpoint, success, error)* | Performs a GET request to the given `endpoint`. |
| --- | --- |
| *doPost(endpoint, data, success, error)* | Performs a POST request with payload `data` to the given `endpoint`. |
| *doPut(endpoint, data, success, error)* | Performs a PUT request witha payload `data` to the given `endpoint`. |
| *doGetFile(endpoint, success, error)* | Performs a GET request to the given `endpoint` to retrieve a file. |
| *doDelete(endpoint, success, error)* | Performs a DELETE request to the given `endpoint`. |

In addition to these methods, the `ServitlyClient` class provides more specific methods to interact with the main object types.

## Thing Methods

| *getMeThings(filter, success, error)* | Retrieves things visible by the logged-in user. |
| --- | --- |
| *getThing(thingId, success, error)* | Retrieves details of a thing by `thingId`. |
| *saveThing(thing, success, error)* | Creates or updates a thing with the given `thing` data. |

## Customer and Location Methods

| *getMeCustomers(filter, success, error)* | Retrieves customers visible to the logged-in user. |
| --- | --- |
| *getCustomer(customerId, success, error)* | Retrieves a customer by `customerId`. |
| *saveCustomer(customer, success, error)* | Creates or updates a customer with the given `customer`data. |
| *getMeLocations(filter, success, error)* | Retrieves locations visible by the logged-in user. |
| *getLocation(customerId, success, error)* | Retrieves a location by `locationId`. |
| *saveLocation(customer, success, error)* | Creates or updates a location with the given `location` data. |

## Metric Data Methods

| *getMetricValues(thingId, metricName, filter, success, error)* | Retrieves the recorded values for the given `thingId` and `metricName`. |
| --- | --- |
| *getLocationMetricValues(locationId, metricName, filter, success, error)* | Retrieves the recorded values for the given `locationId` and `metricName`. |
| *getMetricsLastValue(thingId, metricNames, success, error)* | Retrieves the last recorded value for the given `thingId` and `metricNames`. |
| *setMetricValue(thingId, metricName, timestamp, value, rollbackable, success, error)* | Sets a value for the given `thingId` and `metricName`. |
| *getMetricBlobContent(thingId, metricName, timestamp, success, error)* | Retrieves the content of a BLOB metric value. |

## Statistics Methods

| *getStatisticData(parameters, success, error)* | Compute and return the statistic value for the given `parameters` JSON object, which can contain any of the query parameters supported by the [Statistics API](/apidocs/get-statistic-value) endpoint. |
| --- | --- |

## Event and Work Session Methods

| *getActiveEvents(filter, success, error)* | Retrieves active events. |
| --- | --- |
| *getHistoricalEvents(filter, success, error)* | Retrieves historical events. |
| *getWorkSessions(filter, success, error)* | Retrieves active work sessions. |
| *getHistoricalWorkSessions(filter, success, error)* | Retrieves historical work sessions. |

## Remote Control Methods

| *setConfigurationParameter(thingId, parameterId, value, success, error)* | Sets the `value` for the given `parameterId `and `thingId`. |
| --- | --- |

## Definition Methods

> [!WARNING]
> Client cache
> 
> To optimize the page loading time, the result of the following methods is cached internally by the client, so do not modify any JSON object passed to the success callback. If needed, you can make a local copy into your components. `let clonedMetric = _.cloneDeep(metric);`

| *getMetricDefinitions(thingDefinitionId, success, error)* | Gets the list of metric definitions for the given `thingDefinitionId`. |
| --- | --- |
| *getLocationMetricDefinitions(success, error)* | Gets the list of location metric definitions. |
| *getConfigurationParameters(thingDefinitionId, success, error)* | Gets the list of configuration parameter definitions for the given `thingDefinitionId`. |
| *getConfigurationParameterByName(thingDefinitionId, parameterName, success, error)* | Gets the configuration parameter definition for the given `thingDefinitionId` and `parameterName`. |