Mervis SCADA API

Mervis SCADA offers an open, REST-like API based on JSON and XML data formats for seamless integration with third-party applications. For a full description of advanced features, please contact our technical support.

Important Note on Formatting: While JSON is heavily utilized in newer endpoints, the only officially supported backward-compatible response format across the entire legacy API is XML.

Supported API Methods

Below is the consolidated list of recommended API endpoints. Note: Only methods with fully documented and verified examples are listed below.

Function	Description
Authentication
`api/v2/get/authenticate`	Authenticates a user and returns a session token for subsequent API calls.
Project & Data Structure
`api/get/projects`	Retrieves a list of all projects accessible to the logged-in user.
`api/get/projectByParts`	Retrieves the visual tree structure and the list of datapoints within a specific project.
Reading Data
`api/get/values`	Retrieves the current, real-time values of specified datapoints.
`api/v3/get/history`	Downloads historical trend data for one or multiple series in a single, paginated call.
`api/get/history/specific`	Retrieves specific historical datapoints relative to a provided reference time.
Writing & Execution
`api/set/values`	Writes new values to specified datapoints.
`api/set/executeActions`	Executes predefined actions or buttons (e.g., INIT, ZAP commands) on datapoints.
`api/set/history`	Inserts new historical data values into the database.
`api/replace/history`	Completely replaces existing historical data within a specified time range.

Note on Credentials: You can test these API calls using the credentials `n: demo` and `p: demo`. For production applications, it is required to exchange these credentials for a token using `api/v2/get/authenticate` and use the resulting token (`t: [token_string]`) in subsequent calls to ensure optimal performance.

Authentication

api/v2/get/authenticate

Request:

URL: /api/v2/get/authenticate?format=json
Method: POST

Standard login:

{"data":{"cred":{"n":"demo","p":"demo"}}}

Domain-specific login:

{"data":{"cred":{"d":"GlobalDomain","n":"demo","p":"demo"}}}

Response Properties:

token (string) - Authentication token for calling other API methods.
tokenValidFor (TimeSpan) - The duration for which the provided token is valid (e.g., “P1D” = 1 day).
changePwdBefore (DateTime or null) - Specifies the date and time by which the current password must be changed.

{
    "data": {
        "ChangePwdBefore": null,
        "ClientType": 2,
        "Domain": "3c73477a-6c95-4939-b047-7bbf902bcef1",
        "DomainName": "GlobalDomain",
        "FullName": "GlobalDomain\\demo",
        "Login": "demo",
        "NotifyNearingPwdExpirationIn": null,
        "Token": "3:b83d56f8-2e25-4745-a4e5-1a259c286c5f",
        "TokenValidFor": "P1D",
        "User": "48141739-5d16-4ca3-8ae1-33e27d9eb22e",
        "Username": ""
    },
    "result": { "code": 0, "codeTxt": null, "dataType": null, "desc": null }
}

Reading Data

api/get/values

Retrieves current values of data points (property “Output”) from one or multiple projects.

Request:

URL: /api/get/values?format=xml
Method: POST

{
 "cred": {
  "n": "demo",
  "p": "demo" 
 },
 "propNamesToSerialize": ["Output"],
 "offset": 0,
 "count": 1000,
 "serverState": null,
 "dps": [{
   "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
   "dpIds": ["62cf4083-31ed-4bc1-be25-044ba837a9f0"]
  }]
}

Response:

<?xml version="1.0" encoding="utf-8"?>
<values xmlns:r="http://dev.rcware.eu/serialization/references" nextOffset="-1" serverTime="2026-07-17T10:29:17Z" xmlns:n1="http://dev.rcware.eu/scada/basic-props" xmlns="http://dev.rcware.eu/scada/datapoints">
 <vals>
  <v projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" serverTime="2026-07-17T10:29:17Z">
   <dps>
    <d id="62cf4083-31ed-4bc1-be25-044ba837a9f0" serAlr="true">
     <props>
      <p n="Output" t="2026-07-17T10:29:17Z" q="Good" r:type="b133774d-21ce-42b6-add3-57c012079c55">
       <n1:v>13851.42</n1:v>
      </p>
     </props>
    </d>
   </dps>
  </v>
 </vals>
</values>

api/v3/get/history

Downloading one or multiple trends with a single API call.

Rules:

Items “segmentation”, “requestState”, and “serverState” should always copy the values from the last server response for pagination. The first call should use an empty “segmentation”.

Request:

URL: /api/v3/get/history?format=json
Method: POST

{
    "credentials": {
        "name": "demo",
        "password": "demo"
    },
    "request": {
        "commonSeriesParameters": {
            "from": "2026-06-20T00:00:00Z", 
            "to": "2026-07-17T00:00:00Z"
        },
        "series": [
            {
                "clientReference": "test1",
                "provider": {
                    "parameters": {
                        "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
                        "dataPointId": "62cf4083-31ed-4bc1-be25-044ba837a9f0"
                    }
                }
            }
        ]
    },
    "dataSpecification": {
        "limits": { "count": 1000 }
    },
    "segmentation": {
        "requestState": "", 
        "serverState": "" 
    }
}

Response Details:

v - value
ts - timestamp (start of validity period)
gt - goodthrough (end of validity period)
meta.interval - expected interval between stored records. Useful to identify missing data.

{
    "result": { "code": 0, "subCode": 0, "message": "" },
    "data": {
        "count": 1,
        "historyData": [
            {
                "clientReference": "test1",
                "provider": {
                    "id": "689e32fa-24a2-448e-9374-6158e6e6cb15",
                    "parameters": {
                        "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
                        "dataPointId": "62cf4083-31ed-4bc1-be25-044ba837a9f0"
                    }
                },
                "meta": { "type": "double", "unit": "h", "interval": "PT3M" },
                "values": [
                    { "v": 13851.4, "ts": "2026-06-25T12:00:00.000Z" }
                ]
            }
        ]
    },
    "segmentation": { "requestState": "", "serverState": "" }
}

api/get/history/specific

Request:

URL: /api/get/history/specific?format=json
Method: POST
dataSpec: Defines the specific point to fetch (e.g., 2 = First value less than reference time).
refTime: Reference time required for specific temporal searches.

{
 "cred": {
  "n": "demo",
  "p": "demo"
 },
 "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
 "offset": 0,
 "count": 1000,
 "dataSpec": 2, 
 "refTime": "\/Date(1692788459000)\/",
 "dpIds": ["62cf4083-31ed-4bc1-be25-044ba837a9f0"]
}

Writing Data & Execution

api/set/values

Request:

URL: /api/set/values?format=xml
Method: POST

<?xml version="1.0" encoding="UTF-8"?>
<setValuesRequest xmlns:r="http://dev.rcware.eu/serialization/references" xmlns="http://dev.rcware.eu/scada/datapoints" xmlns:n2="http://dev.rcware.eu/auth" xmlns:n1="http://dev.rcware.eu/scada/comm-props" >
   <n2:cred n="demo" p="demo"/>
        <values projId="1b2623be-eaa4-4e29-8596-c66dd85d5643">
            <dps>
                <d id="07d538d9-9f4b-46ca-ba4d-13b13b5302ff">
                    <props>
                        <p n="Source" t="2024-02-23T09:58:00Z" r:type="1c104bdf-ffcb-4c90-b491-e4781a91ef09">
                            <n1:v>23</n1:v>
                        </p>
                    </props>
                </d>
            </dps>
        </values>
</setValuesRequest>

api/set/executeActions

Request:

URL: /api/set/executeActions?format=xml
Method: POST

<?xml version="1.0" encoding="UTF-8"?>
<executeActionsRequest xmlns="http://dev.rcware.eu/scada/action-defs" xmlns:n2="http://dev.rcware.eu/scada/basic-props" xmlns:n1="http://dev.rcware.eu/auth" xmlns:r="http://dev.rcware.eu/serialization/references">
  <n1:cred n="demo" p="demo"/>
  <actionDefs projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0">
    <actions>
      <actionDefItem propName="INIT" dpId="afc22e18-f8e4-4e08-899c-fb9e4759df3d">
        <execParam r:type="495c9644-eed1-4b94-933b-3fae702a9aca">
          <n2:value>16</n2:value>
        </execParam>
      </actionDefItem>
      <actionDefItem propName="ZAP" dpId="34306c80-73f1-4465-ab51-2b2c1e85ab70">
      </actionDefItem>
    </actions>
  </actionDefs>
</executeActionsRequest>

api/set/history & api/replace/history

Attribute i sets interval (ISO 8601) in which the next value should be expected. All date/time values must be in UTC.

Replace History Request Example:

URL: /api/replace/history?format=xml
Method: POST

<?xml version="1.0" encoding="UTF-8"?>
<replaceHistoryRequest xmlns="http://dev.rcware.eu/scada/history" xmlns:n2="http://dev.rcware.eu/auth" xmlns:n1="http://dev.rcware.eu/scada/basic-props" projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" dpId="e86dba6d-1250-4e7f-aafb-84fd28324710" from="2020-03-15T11:00:00+00:00" to="2020-03-18T11:00:00+00:00">
  <n2:cred n="demo" p="demo"/>
  <vals>
    <hv ts="2020-03-15T11:00:00+00:00" i="P1D">
      <n1:v>2.7</n1:v>
    </hv>
    <hv ts="2020-03-16T11:00:00+00:00" i="P1D">
      <n1:v>3.0</n1:v>
    </hv>
  </vals>
</replaceHistoryRequest>

Projects Management

api/get/projects

Request:

URL: /api/get/projects?format=xml
Method: POST

{
 "cred": {
  "n": "demo",
  "p": "demo"
 },
 "offset": 0,
 "count": 250
}

Response:

<?xml version="1.0" encoding="utf-8"?>
<getProjectsResult xmlns:r="http://dev.rcware.eu/serialization/references" xmlns="http://dev.rcware.eu/scada/projects">
    <projects>
        <project id="2a7f1615-..." name="Weather" />
        <project id="1b2623be-eaa4-4e29-8596-c66dd85d5643" name="SIMPLE_DEMO" />
        <project id="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" name="PLYNOVA_KOTELNA" />
        <project id="b9ad5380-..." name="CVUT_HERBERTOV" />
        <project id="843855a2-..." name="PRVNI_KROKY" />
    </projects>
</getProjectsResult>

api/get/projectByParts

To get the visual tree and list of datapoints.

Request:

URL: /api/get/projectByParts?format=xml
Method: POST

{
 "cred": {
  "n": "demo",
  "p": "demo"
 },
 "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
 "treeId": "Visual tree",
 "partType": 0,
 "offset": 0,
 "count": 250
}

Matlab Client

General Notes

Parameter names ID and Guid are used interchangeably in the Matlab client; it is always a universally unique identifier referring to a project or datapoint.
When plural is used, an array of guids is expected (ie. {'guid1', 'guid2'} ), otherwise just one guid is expected.

ScadaClient

ScadaClient(url, username, password)

Constructor of the Mervis API wrapper.

findAllDPsWithReqTags

findAllDPsWithReqTags(projIds, tags)

Returns list of datapoints based on tags query. Example of tags definition: {'label','indoor_air_temperature';'room_type','office'}

getDpTags

getDpTags(projectId, DpId)

Returns tags of the particular datapoint.

getAllProjectDPs

getAllProjectDPs(projectGuid)

Returns project IDs and names that are accessible to the logged-in user.

getData

[data, time, dataInCell, info] = getData(projID, dpsIds, from, to, span, zone, doublesInterpolationMethod, interpolate_gaps_shorter_than)

Downloads data.

span: sampling interval in seconds, default is 300 sec.
zone: time zone ('local' or 'utc') applied to parameters and output, default is 'local'.
Returns: data (NaN used for missing values), time, dataInCell (useful for strings), and info.

Data Download Example:

scada = ScadaClient('https://scada.mervis.info/','demo','demo'); 
 
dataPointIDs = {'acad79f3-3358-42dd-9b74-98733e63d771','1afa7d9b-1183-4ab1-a6b1-18e464ae2d4d','e496bb8c-14ce-4c2c-b53b-3b71daeabca6'}; 
projectId = '5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0'; 
chartLegend = {'Temp UT1','Temp UT1 Return','Valve Position'}; 
from = now - 4; 
to = now; 
timeSpan = 300; %sec 
 
[data, time] = scada.getData(projectId, dataPointIDs, from, to, timeSpan); 
 
plot(time,data);  
legend(chartLegend); 
datetick;

saveData

saveData(projID, dpID, time, data)

Saves data into the Mervis database.

setDataPointValue

setDataPointValue(projGuid, dpGuid, value, buttonName)

Sets a datapoint value using a button. Only numerical values are supported. Parameter buttonName is not mandatory; 'INIT' is used if undefined.

Example:

dpGuid = 'ccaacb77-295b-48a8-a712-3fb272aa9b6f'; 
projectId = '6b65447e-8622-4a0d-b3b9-42f1d905fdaa'; 
buttonName = 'INIT';
newValue = 1;
 
scada = ScadaClient('https://scada.mervis.info/','demo','demo'); 
scada.setDataPointValue(projectId, dpGuid, newValue, buttonName)

deleteVariable

deleteVariable(projGuid, dpGuid, from, to)

Warning: Deletes data of one variable based on from-to interval. If from-to is not defined, ALL data are deleted. Use carefully, there is no undo!

Table of Contents

Mervis SCADA API

Supported API Methods

Authentication

api/v2/get/authenticate

Reading Data

api/get/values

api/v3/get/history

api/get/history/specific

Writing Data & Execution

api/set/values

api/set/executeActions

api/set/history & api/replace/history

Projects Management

api/get/projects

api/get/projectByParts

Matlab Client

General Notes

ScadaClient

findAllDPsWithReqTags

getDpTags

getAllProjectDPs

getData

saveData

setDataPointValue

deleteVariable