SALT REST Interface

This documentation describes the REST-API Integration of ASCMO Safe Active Learning Transient. The main focus is the JSON data structure of requests and responses, including example calls.

Start the server (ascmo.exe)

The REST server is started via ascmo.exe in saltRestServer mode. The port number is passed as the second parameter.

Call pattern

Copy

"<ASCmoInstallPath>\\ascmo.exe" saltRestServer "<PORT>"

Example

Copy

"C:\\Program Files\\ETAS\\ASCMO\\ascmo.exe" saltRestServer "5556"

Basic information

Base URL (local): http://localhost:<PORT>
Base URL (network): http://<SERVER_IP>:<PORT> (e.g. http://192.168.1.100:5556)
Methods: all endpoints use POST
Success format: JSON object
Error format (current behavior): HTTP 400 with plain-text body (no JSON error object)

POST /alive

Functionality

Liveness check. Always callable.

Request JSON

Body can be empty ("") or {}

Response JSON (200)

Copy

{}

Example request

Copy

POST /alive
Content-Type: application/json

{}

Example response

Copy

{}

POST /get-state

Functionality

Returns the current server state. Always callable, regardless of server state (like /alive).

Request JSON

Body can be empty ("") or {}

Response JSON (200)

Copy

{
  "status": "string",
  "dataset_index": null
}

Fields

status (string) – one of "unconfigured", "pending", "idle", "dataset_started", "closing"
dataset_index (number / u64 | null) – the index of the active dataset when status is "dataset_started", otherwise null

Example request

Copy

POST /get-state
Content-Type: application/json

{}

Example responses

Server just started:

Copy

{
  "status": "unconfigured",
  "dataset_index": null
}

Configuration pending:

Copy

{
  "status": "pending",
  "dataset_index": null
}

Configuration loaded, no dataset running:

Copy

{
  "status": "idle",
  "dataset_index": null
}

Dataset running:

Copy

{
  "status": "dataset_started",
  "dataset_index": 1
}

Closing:

Copy

{
  "status": "closing",
  "dataset_index": null
}

POST /load-configuration

Functionality

Loads a SALT configuration and defines the path for the result project. Callable only when the current configuration is closed or at startup.

Request JSON

Copy

{
  "configuration_file": "string",
  "result_file": "string"
}

Fields

configuration_file (string, required) – path to the .salt configuration file
result_file (string, required) – path to the .salt result file

Response JSON (200)

Copy

{}

Errors

400 server is already configured or configuration is pending

Example request

Copy

POST /load-configuration
Content-Type: application/json

{
  "configuration_file": "C:/test/config.salt",
  "result_file": "C:/test/result.salt"
}

Example response

Copy

{}

POST /get-labels

Functionality

Returns the required label names of the loaded configuration grouped by category. Callable once a configuration is loaded.

Request JSON

Copy

{}

Response JSON (200)

Copy

{
  "inputs": ["string", "string"],
  "outputs": ["string", "string"],
  "additionalLabels": ["string", "string"]
}

Fields

inputs (Array<string>) – configurable input labels
outputs (Array<string>) – configured output labels
additionalLabels (Array<string>) – additional labels

Errors

400 server is not configured
400 server is closing

Example request

Copy

POST /get-labels
Content-Type: application/json

{}

Example response

Copy

{
  "inputs": ["X1", "X2"],
  "outputs": ["Y1", "Y_2"],
  "additionalLabels": ["Label1", "Label2", "Label3"],
}

POST /start-dataset

Functionality

Starts a new dataset and returns dataset_index for all subsequent calls. The initial measurement values are provided directly. Callable once a configuration is loaded.

Request JSON

Copy

{
  "data": {
    "<labelName>": 0.0
  }
}

Fields

data (Object<string, number>, required) – initial value per label

Response JSON (200)

Copy

{
  "dataset_index": 1
}

Fields

dataset_index (number / u64)

Errors

400 server is not configured
400 server is closing
400 dataset is already started

Example request

Copy

POST /start-dataset
Content-Type: application/json

{
  "data": {
    "X1": 1.0,
    "X2": 2.0,
    "Y1": 3.0,
  }
}

Example response

Copy

{
  "dataset_index": 1
}

POST /get-trajectory

Functionality

Returns the planned trajectory starting at start_index. Optionally, the maximum duration can be limited via max_duration_secs. Only data for configured inputs is returned. Callable once a dataset has been started.

Request JSON

Copy

{
  "dataset_index": 1,
  "start_index": 1,
  "max_duration_secs": 30
}

Fields

dataset_index (number / u64, required)
start_index (number / u64, required, 1-based)
max_duration_secs (number, optional)

Response JSON (200)

Copy

{
  "content": {
    "start_index": 1,
    "end_index": 3,
    "sample_time": 0.1,
    "data": {
      "X1": [1.0, 1.5, 2],
      "X2": [2.0, 3.0, 4.0]
    }
  }
}

If no trajectory is available:

Copy

{
  "content": null
}

Fields in content

start_index (number / u64)
end_index (number / u64)
sample_time (number)
data (Object<string, Array<number>>)

Errors

400 dataset is not started yet
400 unexpected dataset index
400 server is not configured
400 server is closing

Example request

Copy

POST /get-trajectory
Content-Type: application/json

{
  "dataset_index": 1,
  "start_index": 1,
  "max_duration_secs": 3
}

Example response

Copy

{
  "content": {
    "start_index": 1,
    "end_index": 3,
    "sample_time": 1.0,
    "data": {
      "X1": [1.0, 1.5, 2],
      "X2": [2.0, 3.0, 4.0]
    }
  }
}

POST /send-measurement-data

Functionality

Transfers measurement data for a started dataset for the labels returned by get-labels, inputs and outputs are mandatory. end_index describes the point up to which measurements have already been taken in the requested trajectory. Callable once a dataset has been started.

Request JSON

Copy

{
  "dataset_index": 1,
  "end_index": 3,
  "time": [0.0, 0.9, 2.1],
  "data": {
    "X1": [1.1, 1.55, 2.02],
    "X2": [1.9, 3.1, 4.0],
    "Y1": [3.2, 5.2, 6.0]
  }
}

Fields

dataset_index (number / u64, required)
end_index (number / u64, required, 1-based)
time (Array<number>, required)
data (Object<string, Array<number>>, required)

Response JSON (200)

Copy

{}

Errors

400 dataset is not started yet
400 unexpected dataset index
400 length of time vector is not equal to length of data vectors for at least one label
400 server is not configured
400 server is closing

Example request

Copy

POST /send-measurement-data
Content-Type: application/json

{
  "dataset_index": 1,
  "end_index": 3,
  "time": [0.0, 0.9, 2.1],
  "data": {
    "X1": [1.1, 1.55, 2.02],
    "X2": [1.9, 3.1, 4.0],
    "Y1": [3.2, 5.2, 6.0]
  }
}

Example response

Copy

{}

POST /finish-dataset

Functionality

Marks a started dataset as finished. Callable once a dataset has been started.

Request JSON

Copy

{
  "dataset_index": 1
}

Fields

dataset_index (number / u64, required)

Response JSON (200)

Copy

{}

Errors

400 dataset is not started yet
400 unexpected dataset index
400 server is not configured
400 server is closing

Example request

Copy

POST /finish-dataset
Content-Type: application/json

{
  "dataset_index": 1
}

Example response

Copy

{}

POST /close-configuration

Functionality

Initiates closing of the current configuration. Callable when no dataset is started and a configuration is loaded.

Request JSON

Copy

{}

Response JSON (200)

Copy

{}

Errors

400 server is not configured

Example request

Copy

POST /close-configuration
Content-Type: application/json

{}

Example response

Copy

{}