Skip to main content

OIBus API Reference

The OIBus REST API lets you automate every aspect of an OIBus instance: configure connectors and scan modes, push data directly into North connector caches, search logs, manage users, and monitor engine health — all over HTTP.

Base URL​

http://<oibus-host>:2223

The default port is 2223. Replace <oibus-host> with the hostname or IP address of the machine running OIBus.

Authentication​

Every request must be authenticated. OIBus supports two methods:

MethodWhen to use
JWT (Bearer token)Interactive sessions. Obtain a token by POST /api/users/authenticate with { login, password }. Pass it as Authorization: Bearer <token>. Tokens are valid for 7 days and are invalidated if the password changes.
HTTP Basic AuthScripts and automation. Pass credentials as Authorization: Basic <base64(login:password)>. Prefer running scripts on the OIBus host (localhost) so credentials are not transmitted over the network in cleartext.

Common patterns​

Pagination — list endpoints that return Page<T> accept a page query parameter (zero-based). The response includes totalElements, totalPages, size, and number.

Comma-separated multi-values — some query parameters (e.g. northId, levels, types, status) accept multiple values as a comma-separated string: ?levels=error,warn.

204 No Content — PUT and DELETE operations return 204 on success with an empty body.

API docs by Redocly

OIBus API (3.8.2)

Download OpenAPI specification:

Optimistik SAS: oibus@optimistik.com URL: https://www.optimistik.com/ License: EUPL

OIBus API is a RESTful interface for managing industrial data flows. It allows you to configure connectors, schedule data collection, transform and route data, monitor system health, and secure communications. Designed for developers and system integrators, it enables seamless integration between industrial systems and enterprise applications.

North Connectors

Endpoints for managing north connectors and their cache operations

List all north connector types

Retrieves a list of all available north connector types

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get north connector manifest

Retrieves a specific north connector manifest by its type

path Parameters
type
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "opcua",
  • "category": "file",
  • "types": [
    ],
  • "settings": {
    }
}

List all north connectors

Retrieves a list of all configured north connectors

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create north connector

Creates a new north connector with the provided configuration

query Parameters
duplicate
required
string
Request Body schema: application/json
required
Any of
name
required
string

The name of the North connector.

type
required
string
Value: "aws-s3"

The type of the North connector.

description
required
string

The description of the North connector.

enabled
required
boolean

Whether the North connector is enabled.

required
object (NorthAmazonS3Settings)
required
object

The caching configuration for the North connector.

required
Array of objects (TransformerCommandDTOWithOptions)

The list of transformers to apply to the data.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Debug Console Output",
  • "type": "console",
  • "description": "Outputs data to console for debugging purposes",
  • "enabled": true,
  • "settings": {
    },
  • "caching": {
    },
  • "transformers": [ ]
}

Response samples

Content type
application/json
Example
{
  • "id": "entity123",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z",
  • "name": "Debug Console Output",
  • "type": "console",
  • "description": "Outputs data to console for debugging purposes",
  • "enabled": true,
  • "settings": {
    },
  • "caching": {
    },
  • "transformers": [
    ]
}

Get north connector by ID

Retrieves a specific north connector by its unique identifier

path Parameters
northId
required
string

Responses

Response samples

Content type
application/json
Example
{
  • "id": "entity123",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z",
  • "name": "Debug Console Output",
  • "type": "console",
  • "description": "Outputs data to console for debugging purposes",
  • "enabled": true,
  • "settings": {
    },
  • "caching": {
    },
  • "transformers": [
    ]
}

Update north connector

Updates an existing north connector configuration

path Parameters
northId
required
string
Request Body schema: application/json
required
Any of
name
required
string

The name of the North connector.

type
required
string
Value: "aws-s3"

The type of the North connector.

description
required
string

The description of the North connector.

enabled
required
boolean

Whether the North connector is enabled.

required
object (NorthAmazonS3Settings)
required
object

The caching configuration for the North connector.

required
Array of objects (TransformerCommandDTOWithOptions)

The list of transformers to apply to the data.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Debug Console Output",
  • "type": "console",
  • "description": "Outputs data to console for debugging purposes",
  • "enabled": true,
  • "settings": {
    },
  • "caching": {
    },
  • "transformers": [ ]
}

Delete north connector

Deletes a north connector by its ID

path Parameters
northId
required
string

Responses

Start north connector

Starts a north connector

path Parameters
northId
required
string

Responses

Stop north connector

Stops a north connector

path Parameters
northId
required
string

Responses

Reset north connector metrics

Resets all metrics for a north connector

path Parameters
northId
required
string

Responses

Test north connection

Tests the connection for a north connector

path Parameters
northId
required
string
query Parameters
northType
required
string (OIBusNorthType)
Enum: "opcua" "mqtt" "modbus" "oianalytics" "rest" "sftp" "aws-s3" "azure-blob" "console" "file-writer"

Type representing the possible types for a North connector.

Request Body schema: application/json
required
Any of
bucket
required
string
region
required
string
folder
required
string
accessKey
required
string
secretKey
required
string or null
useProxy
required
boolean
proxyUrl
string or null
proxyUsername
string or null
proxyPassword
string or null

Responses

Request samples

Content type
application/json
Example
{
  • "bucket": "string",
  • "region": "string",
  • "folder": "string",
  • "accessKey": "string",
  • "secretKey": "string",
  • "useProxy": true,
  • "proxyUrl": "string",
  • "proxyUsername": "string",
  • "proxyPassword": "string"
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add/edit transformer

Adds or updates a transformer configuration for a north connector

path Parameters
northId
required
string
Request Body schema: application/json
required
id
required
string

The id used to match a transformer with options

required
SourceOriginSouthDTO (object) or SourceOriginOIAnalyticsDTO (object) or SourceOriginAPIDTO (object) (TransformerSourceDTO)
required
CustomTransformerDTO (object) or StandardTransformerDTO (object) (TransformerDTO)

Union type representing either a custom or standard transformer.

options
required
object (Record_string.unknown_)

Construct a type with a set of properties K of type T

Responses

Request samples

Content type
application/json
{
  • "id": "id",
  • "source": {
    },
  • "transformer": {
    },
  • "options": {
    }
}

Remove transformer

Remove a transformer from a north connector

path Parameters
northId
required
string
transformerId
required
string

Responses

Search files in cache, error and archive folders

Searches for files in the north connector cache

path Parameters
northId
required
string
query Parameters
nameContains
required
string
start
required
string
end
required
string
maxNumberOfFilesReturned
required
number <double>

Responses

Response samples

Content type
application/json
{
  • "searchDate": "2023-10-31T12:34:56.789Z",
  • "metrics": {
    },
  • "error": [
    ],
  • "archive": [
    ],
  • "cache": [
    ]
}

Retrieve cache file content

Retrieve a file from a north connector cache

path Parameters
northId
required
string
filename
required
string
query Parameters
folder
required
string (DataFolderType)
Enum: "cache" "error" "archive"

Responses

Response samples

Content type
application/json
{
  • "content": "string",
  • "contentFilename": "string",
  • "contentType": "csv",
  • "truncated": true,
  • "totalSize": 0.1
}

Move or remove files from cache, error and archive folders

Update cache content by moving or removing files from cache, archive and error folders

path Parameters
northId
required
string
Request Body schema: application/json
required
required
object
required
object
required
object

Responses

Request samples

Content type
application/json
{
  • "cache": {
    },
  • "error": {
    },
  • "archive": {
    }
}

South Connectors

Endpoints for managing south connectors, items, and related operations

List all south connector types

Retrieves a list of all available south connector types

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get south connector manifest

Retrieves a specific south connector manifest by its type

path Parameters
type
required
string (OIBusSouthType)
Enum: "opcua" "mqtt" "modbus" "oianalytics" "ads" "folder-scanner" "ftp" "mssql" "mysql" "odbc" "oledb" "opc" "oracle" "osisoft-pi" "postgresql" "rest" "sftp" "sqlite"

Type representing the possible types for a South connector.

Responses

Response samples

Content type
application/json
{
  • "id": "opcua",
  • "category": "file",
  • "modes": {
    },
  • "settings": {
    },
  • "items": {
    }
}

List all south connectors

Retrieves a list of all configured south connectors

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create south connector

Creates a new south connector with the provided configuration

query Parameters
duplicate
required
string
Request Body schema: application/json
required
Any of
name
required
string

The name of the South connector.

type
required
string
Value: "ads"

The type of the South connector.

description
required
string

Description of the South connector's purpose.

enabled
required
boolean

Whether the South connector should be enabled.

required
object (SouthADSSettings)
required
Array of objects (SouthConnectorADSItemCommandDTO)

List of items (data points) to configure for this connector.

required
Array of objects (SouthItemGroupCommandDTO)

List of groups used to gather items

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Production Data Files",
  • "type": "folder-scanner",
  • "description": "Scans production data CSV files",
  • "enabled": true,
  • "settings": {
    },
  • "items": [
    ],
  • "groups": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "id": "entity123",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z",
  • "name": "Production Data Files",
  • "type": "folder-scanner",
  • "description": "Scans production data CSV files",
  • "enabled": true,
  • "settings": {
    },
  • "items": [
    ],
  • "groups": [
    ]
}

Get south connector by ID

Retrieves a specific south connector by its unique identifier

path Parameters
southId
required
string

Responses

Response samples

Content type
application/json
Example
{
  • "id": "entity123",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z",
  • "name": "Production Data Files",
  • "type": "folder-scanner",
  • "description": "Scans production data CSV files",
  • "enabled": true,
  • "settings": {
    },
  • "items": [
    ],
  • "groups": [
    ]
}

Update south connector

Updates an existing south connector configuration

path Parameters
southId
required
string
Request Body schema: application/json
required
Any of
name
required
string

The name of the South connector.

type
required
string
Value: "ads"

The type of the South connector.

description
required
string

Description of the South connector's purpose.

enabled
required
boolean

Whether the South connector should be enabled.

required
object (SouthADSSettings)
required
Array of objects (SouthConnectorADSItemCommandDTO)

List of items (data points) to configure for this connector.

required
Array of objects (SouthItemGroupCommandDTO)

List of groups used to gather items

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Production Data Files",
  • "type": "folder-scanner",
  • "description": "Scans production data CSV files",
  • "enabled": true,
  • "settings": {
    },
  • "items": [
    ],
  • "groups": [
    ]
}

Delete south connector

Deletes a south connector by its ID

path Parameters
southId
required
string

Responses

Start south connector

Start a south connector

path Parameters
southId
required
string

Responses

Stop south connector

Stop a south connector

path Parameters
southId
required
string

Responses

Reset south connector metrics

Resets all metrics for a north connector

path Parameters
southId
required
string

Responses

Test south connection

Tests the connection for a south connector

path Parameters
southId
required
string
query Parameters
southType
required
string (OIBusSouthType)
Enum: "opcua" "mqtt" "modbus" "oianalytics" "ads" "folder-scanner" "ftp" "mssql" "mysql" "odbc" "oledb" "opc" "oracle" "osisoft-pi" "postgresql" "rest" "sftp" "sqlite"

Type representing the possible types for a South connector.

Request Body schema: application/json
required
Any of
netId
required
string
port
required
number <double>
routerAddress
required
string or null
routerTcpPort
required
number or null <double>
clientAmsNetId
required
string or null
clientAdsPort
required
number or null <double>
retryInterval
required
number <double>
plcName
required
string or null
enumAsText
required
string (SouthADSSettingsEnumAsText)
Enum: "text" "integer"
boolAsText
required
string (SouthADSSettingsBoolAsText)
Enum: "text" "integer"
required
Array of objects or null (SouthADSSettingsStructureFiltering)

Responses

Request samples

Content type
application/json
Example
{
  • "netId": "string",
  • "port": 0.1,
  • "routerAddress": "string",
  • "routerTcpPort": 0.1,
  • "clientAmsNetId": "string",
  • "clientAdsPort": 0.1,
  • "retryInterval": 0.1,
  • "plcName": "string",
  • "enumAsText": "text",
  • "boolAsText": "text",
  • "structureFiltering": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Test south connector item

Test a south connector item

path Parameters
southId
required
string
query Parameters
southType
required
string (OIBusSouthType)
Enum: "opcua" "mqtt" "modbus" "oianalytics" "ads" "folder-scanner" "ftp" "mssql" "mysql" "odbc" "oledb" "opc" "oracle" "osisoft-pi" "postgresql" "rest" "sftp" "sqlite"

Type representing the possible types for a South connector.

itemName
required
string
Request Body schema: application/json
required
required
SouthADSSettings (object) or SouthFolderScannerSettings (object) or SouthFTPSettings (object) or SouthModbusSettings (object) or SouthMQTTSettings (object) or SouthMSSQLSettings (object) or SouthMySQLSettings (object) or SouthODBCSettings (object) or SouthOIAnalyticsSettings (object) or SouthOLEDBSettings (object) or SouthOPCSettings (object) or SouthOPCUASettings (object) or SouthOracleSettings (object) or SouthPISettings (object) or SouthPostgreSQLSettings (object) or SouthRestSettings (object) or SouthSFTPSettings (object) or SouthSQLiteSettings (object) (SouthSettings)
required
SouthADSItemSettings (object) or SouthFolderScannerItemSettings (object) or SouthFTPItemSettings (object) or SouthModbusItemSettings (object) or SouthMQTTItemSettings (object) or SouthMSSQLItemSettings (object) or SouthMySQLItemSettings (object) or SouthODBCItemSettings (object) or SouthOIAnalyticsItemSettings (object) or SouthOLEDBItemSettings (object) or SouthOPCItemSettings (object) or SouthOPCUAItemSettings (object) or SouthOracleItemSettings (object) or SouthPIItemSettings (object) or SouthPostgreSQLItemSettings (object) or SouthRestItemSettings (object) or SouthSFTPItemSettings (object) or SouthSQLiteItemSettings (object) (SouthItemSettings)
required
object (SouthConnectorItemTestingSettings)

Settings for testing a South connector item. Used when manually testing data collection for an item.

Responses

Request samples

Content type
application/json
{
  • "southSettings": {
    },
  • "itemSettings": {
    },
  • "testingSettings": {
    }
}

Response samples

Content type
application/json
Example
{
  • "type": "time-values",
  • "content": [
    ]
}

List south connector items

List all items for a south connector

path Parameters
southId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Search south connector items

Searches for items in a south connector with optional filtering

path Parameters
southId
required
string
query Parameters
name
required
string
scanModeId
required
string
enabled
required
boolean
page
number <double>
Default: 0

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "totalElements": 2,
  • "size": 10,
  • "number": 0,
  • "totalPages": 1
}

Get south connector item

Retrieves a specific item from a south connector

path Parameters
southId
required
string
itemId
required
string

Responses

Response samples

Content type
application/json
Example
{
  • "id": "entity123",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z",
  • "name": "Temperature Logs",
  • "enabled": true,
  • "settings": {
    },
  • "scanMode": {
    },
  • "group": {
    },
  • "syncWithGroup": true,
  • "maxReadInterval": 3600,
  • "readDelay": 200,
  • "overlap": 1000
}

Update south connector item

Updates an existing item in a south connector

path Parameters
southId
required
string
itemId
required
string
Request Body schema: application/json
required
Any of
id
required
string or null

The ID of the item (null when creating a new item).

enabled
required
boolean

Whether this item should be enabled.

name
required
string

The name of the item.

required
object (SouthADSItemSettings)
scanModeId
required
string or null

The ID of the scan mode to use for this item. Null when the scan mode should be determined by the system.

scanModeName
required
string or null

The name of the scan mode to use when ID is not available. Null when not specifying by name.

groupId
required
string or null

The ID of the group this item belongs to. Null when the item is not in any group.

groupName
required
string or null

The name of the group this item belongs to. Used when importing from CSV where group IDs are not available. Null when the item is not in any group.

syncWithGroup
required
boolean

Whether this item syncs its historian settings with its group. When true, historian fields are inherited from the group.

maxReadInterval
required
number or null <double>

Maximum read interval in seconds for historical queries. Only applicable for connectors with historian capabilities. When null and item is in a group, inherits from group settings.

readDelay
required
number or null <double>

Read delay in milliseconds before querying historical data. Only applicable for connectors with historian capabilities. When null and item is in a group, inherits from group settings.

overlap
required
number or null <double>

Default overlap in milliseconds for historical queries. Only applicable for connectors with historian capabilities. When null and item is in a group, inherits from group settings.

Responses

Request samples

Content type
application/json
Example
{
  • "id": null,
  • "enabled": true,
  • "name": "Temperature Logs",
  • "settings": {
    },
  • "scanModeId": "periodic-5min",
  • "scanModeName": null,
  • "groupId": "group-123",
  • "groupName": "Production Line A",
  • "syncWithGroup": true,
  • "maxReadInterval": 3600,
  • "readDelay": 200,
  • "overlap": 1000
}

Delete south item

Delete a south item

path Parameters
southId
required
string
itemId
required
string

Responses

Get item last value

Retrieves the last cached value for a specific item

path Parameters
southId
required
string
itemId
required
string

Responses

Response samples

Content type
application/json
{
  • "itemId": "item-123",
  • "itemName": "Temperature Sensor 1",
  • "groupId": "group-123",
  • "groupName": "Temperature Group",
  • "queryTime": "2024-02-02T12:00:00.000Z",
  • "value": null,
  • "trackedInstant": "2024-02-02T12:00:00.000Z"
}

Create south connector item

Creates a new item in a south connector

path Parameters
southId
required
string
Request Body schema: application/json
required
Any of
id
required
string or null

The ID of the item (null when creating a new item).

enabled
required
boolean

Whether this item should be enabled.

name
required
string

The name of the item.

required
object (SouthADSItemSettings)
scanModeId
required
string or null

The ID of the scan mode to use for this item. Null when the scan mode should be determined by the system.

scanModeName
required
string or null

The name of the scan mode to use when ID is not available. Null when not specifying by name.

groupId
required
string or null

The ID of the group this item belongs to. Null when the item is not in any group.

groupName
required
string or null

The name of the group this item belongs to. Used when importing from CSV where group IDs are not available. Null when the item is not in any group.

syncWithGroup
required
boolean

Whether this item syncs its historian settings with its group. When true, historian fields are inherited from the group.

maxReadInterval
required
number or null <double>

Maximum read interval in seconds for historical queries. Only applicable for connectors with historian capabilities. When null and item is in a group, inherits from group settings.

readDelay
required
number or null <double>

Read delay in milliseconds before querying historical data. Only applicable for connectors with historian capabilities. When null and item is in a group, inherits from group settings.

overlap
required
number or null <double>

Default overlap in milliseconds for historical queries. Only applicable for connectors with historian capabilities. When null and item is in a group, inherits from group settings.

Responses

Request samples

Content type
application/json
Example
{
  • "id": null,
  • "enabled": true,
  • "name": "Temperature Logs",
  • "settings": {
    },
  • "scanModeId": "periodic-5min",
  • "scanModeName": null,
  • "groupId": "group-123",
  • "groupName": "Production Line A",
  • "syncWithGroup": true,
  • "maxReadInterval": 3600,
  • "readDelay": 200,
  • "overlap": 1000
}

Response samples

Content type
application/json
Example
{
  • "id": "entity123",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z",
  • "name": "Temperature Logs",
  • "enabled": true,
  • "settings": {
    },
  • "scanMode": {
    },
  • "group": {
    },
  • "syncWithGroup": true,
  • "maxReadInterval": 3600,
  • "readDelay": 200,
  • "overlap": 1000
}

Delete all south connector items

Deletes all items from a south connector

path Parameters
southId
required
string

Responses

Enable south connector item

Enable a south connector item

path Parameters
southId
required
string
itemId
required
string

Responses

Disable south connector item

Disable a south connector item

path Parameters
southId
required
string
itemId
required
string

Responses

Enable south connector items

Enable a list of south connector items

path Parameters
southId
required
string
Request Body schema: application/json
required
itemIds
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "itemIds": [
    ]
}

Disable south connector items

Disable a list of south connector items

path Parameters
southId
required
string
Request Body schema: application/json
required
itemIds
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "itemIds": [
    ]
}

Delete south connector items

Delete a list of south connector items

path Parameters
southId
required
string
Request Body schema: application/json
required
itemIds
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "itemIds": [
    ]
}

Convert items to CSV

Converts frontend in memory items to CSV format

path Parameters
southType
required
string
Request Body schema: multipart/form-data
required
delimiter
required
string
items
required
string <binary>

Responses

Export items to CSV

Exports all items from a history query as a CSV file

path Parameters
southId
required
string
Request Body schema: application/json
required
delimiter
required
string

CSV delimiter character

Responses

Request samples

Content type
application/json
{
  • "delimiter": "string"
}

Check CSV import

Validates a CSV file before import and checks for conflicts with existing items

path Parameters
southType
required
string
Request Body schema: multipart/form-data
required
delimiter
required
string
deleteItemsNotPresent
required
string
itemsToImport
required
string <binary>
currentItems
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "errors": [
    ]
}

Import items from CSV

Imports items from a CSV file into a history query

path Parameters
southId
required
string
Request Body schema: multipart/form-data
required
items
required
string <binary>
deleteItemsNotPresent
required
string

Responses

List south item groups

Lists all groups for a south connector

path Parameters
southId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create south item group

Creates a new group for a south connector

path Parameters
southId
required
string
Request Body schema: application/json
required
id
required
string or null

The ID of the group (null when creating a new group).

required
object
required
object

Responses

Request samples

Content type
application/json
{
  • "id": null,
  • "standardSettings": {
    },
  • "historySettings": {
    }
}

Response samples

Content type
application/json
{
  • "id": "entity123",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z",
  • "standardSettings": {
    },
  • "historySettings": {
    }
}

Get south item group

Gets a specific group by ID

path Parameters
southId
required
string
groupId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "entity123",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z",
  • "standardSettings": {
    },
  • "historySettings": {
    }
}

Update south item group

Updates an existing group

path Parameters
southId
required
string
groupId
required
string
Request Body schema: application/json
required
id
required
string or null

The ID of the group (null when creating a new group).

required
object
required
object

Responses

Request samples

Content type
application/json
{
  • "id": null,
  • "standardSettings": {
    },
  • "historySettings": {
    }
}

Delete south item group

Deletes a group

path Parameters
southId
required
string
groupId
required
string

Responses

Move items to group

Moves items to a group (or removes them from a group if groupId is null)

path Parameters
southId
required
string
Request Body schema: application/json
required
groupId
required
string or null
itemIds
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "groupId": "string",
  • "itemIds": [
    ]
}

History Queries

Endpoints for managing history queries, items, and cache operations

List all history queries

Retrieves a list of all configured history queries

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create history query

Creates a new history query with the provided configuration

query Parameters
fromSouth
required
string
fromNorth
required
string
duplicate
required
string
Request Body schema: application/json
required
Any of
northType
required
string
Value: "aws-s3"
required
object (NorthAmazonS3Settings)
name
required
string
description
required
string
required
object
required
object
required
Array of objects (HistoryTransformerCommandDTOWithOptions)

Responses

Request samples

Content type
application/json
Example
{
  • "northType": "aws-s3",
  • "northSettings": {
    },
  • "name": "string",
  • "description": "string",
  • "queryTimeRange": {
    },
  • "caching": {
    },
  • "northTransformers": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "northType": "aws-s3",
  • "northSettings": {
    },
  • "id": "entity123",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z",
  • "name": "Production Data Migration",
  • "description": "Migrate production data from old to new system",
  • "status": "PENDING",
  • "queryTimeRange": {
    },
  • "caching": {
    },
  • "northTransformers": [
    ]
}

Get history query by ID

Retrieves a specific history query by its unique identifier

path Parameters
historyId
required
string

Responses

Response samples

Content type
application/json
Example
{
  • "northType": "aws-s3",
  • "northSettings": {
    },
  • "id": "entity123",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z",
  • "name": "Production Data Migration",
  • "description": "Migrate production data from old to new system",
  • "status": "PENDING",
  • "queryTimeRange": {
    },
  • "caching": {
    },
  • "northTransformers": [
    ]
}

Update history query

Updates an existing history query configuration

path Parameters
historyId
required
string
query Parameters
resetCache
required
string
Request Body schema: application/json
required
Any of
northType
required
string
Value: "aws-s3"
required
object (NorthAmazonS3Settings)
name
required
string
description
required
string
required
object
required
object
required
Array of objects (HistoryTransformerCommandDTOWithOptions)

Responses

Request samples

Content type
application/json
Example
{
  • "northType": "aws-s3",
  • "northSettings": {
    },
  • "name": "string",
  • "description": "string",
  • "queryTimeRange": {
    },
  • "caching": {
    },
  • "northTransformers": [
    ]
}

Delete history query

Deletes a history query by its ID

path Parameters
historyId
required
string

Responses

Start history query

Starts a history query

path Parameters
historyId
required
string

Responses

Pause history query

Pause a history query

path Parameters
historyId
required
string

Responses

Test north connection

Test north connection for a history query

path Parameters
historyId
required
string
query Parameters
northType
required
string (OIBusNorthType)
Enum: "opcua" "mqtt" "modbus" "oianalytics" "rest" "sftp" "aws-s3" "azure-blob" "console" "file-writer"

Type representing the possible types for a North connector.

fromNorth
required
string
Request Body schema: application/json
required
Any of
bucket
required
string
region
required
string
folder
required
string
accessKey
required
string
secretKey
required
string or null
useProxy
required
boolean
proxyUrl
string or null
proxyUsername
string or null
proxyPassword
string or null

Responses

Request samples

Content type
application/json
Example
{
  • "bucket": "string",
  • "region": "string",
  • "folder": "string",
  • "accessKey": "string",
  • "secretKey": "string",
  • "useProxy": true,
  • "proxyUrl": "string",
  • "proxyUsername": "string",
  • "proxyPassword": "string"
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Test south connection

Test south connection for a history query

path Parameters
historyId
required
string
query Parameters
southType
required
string (OIBusSouthType)
Enum: "opcua" "mqtt" "modbus" "oianalytics" "ads" "folder-scanner" "ftp" "mssql" "mysql" "odbc" "oledb" "opc" "oracle" "osisoft-pi" "postgresql" "rest" "sftp" "sqlite"

Type representing the possible types for a South connector.

fromSouth
required
string
Request Body schema: application/json
required
Any of
netId
required
string
port
required
number <double>
routerAddress
required
string or null
routerTcpPort
required
number or null <double>
clientAmsNetId
required
string or null
clientAdsPort
required
number or null <double>
retryInterval
required
number <double>
plcName
required
string or null
enumAsText
required
string (SouthADSSettingsEnumAsText)
Enum: "text" "integer"
boolAsText
required
string (SouthADSSettingsBoolAsText)
Enum: "text" "integer"
required
Array of objects or null (SouthADSSettingsStructureFiltering)

Responses

Request samples

Content type
application/json
Example
{
  • "netId": "string",
  • "port": 0.1,
  • "routerAddress": "string",
  • "routerTcpPort": 0.1,
  • "clientAmsNetId": "string",
  • "clientAdsPort": 0.1,
  • "retryInterval": 0.1,
  • "plcName": "string",
  • "enumAsText": "text",
  • "boolAsText": "text",
  • "structureFiltering": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Test history query item

Test a history query item

path Parameters
historyId
required
string
query Parameters
southType
required
string (OIBusSouthType)
Enum: "opcua" "mqtt" "modbus" "oianalytics" "ads" "folder-scanner" "ftp" "mssql" "mysql" "odbc" "oledb" "opc" "oracle" "osisoft-pi" "postgresql" "rest" "sftp" "sqlite"

Type representing the possible types for a South connector.

itemName
required
string
fromSouth
required
string
Request Body schema: application/json
required
required
SouthADSSettings (object) or SouthFolderScannerSettings (object) or SouthFTPSettings (object) or SouthModbusSettings (object) or SouthMQTTSettings (object) or SouthMSSQLSettings (object) or SouthMySQLSettings (object) or SouthODBCSettings (object) or SouthOIAnalyticsSettings (object) or SouthOLEDBSettings (object) or SouthOPCSettings (object) or SouthOPCUASettings (object) or SouthOracleSettings (object) or SouthPISettings (object) or SouthPostgreSQLSettings (object) or SouthRestSettings (object) or SouthSFTPSettings (object) or SouthSQLiteSettings (object) (SouthSettings)
required
SouthADSItemSettings (object) or SouthFolderScannerItemSettings (object) or SouthFTPItemSettings (object) or SouthModbusItemSettings (object) or SouthMQTTItemSettings (object) or SouthMSSQLItemSettings (object) or SouthMySQLItemSettings (object) or SouthODBCItemSettings (object) or SouthOIAnalyticsItemSettings (object) or SouthOLEDBItemSettings (object) or SouthOPCItemSettings (object) or SouthOPCUAItemSettings (object) or SouthOracleItemSettings (object) or SouthPIItemSettings (object) or SouthPostgreSQLItemSettings (object) or SouthRestItemSettings (object) or SouthSFTPItemSettings (object) or SouthSQLiteItemSettings (object) (SouthItemSettings)
required
object

Testing settings including time range

Responses

Request samples

Content type
application/json
{
  • "southSettings": {
    },
  • "itemSettings": {
    },
  • "testingSettings": {
    }
}

Response samples

Content type
application/json
Example
{
  • "type": "time-values",
  • "content": [
    ]
}

List history query items

List all items for a history query

path Parameters
historyId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Search history query items

Searches for items in a history query with optional filtering

path Parameters
historyId
required
string
query Parameters
name
required
string
enabled
required
boolean
page
number <double>
Default: 0

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "totalElements": 2,
  • "size": 10,
  • "number": 0,
  • "totalPages": 1
}

Get history query item

Retrieves a specific item from a history query

path Parameters
historyId
required
string
itemId
required
string

Responses

Response samples

Content type
application/json
Example
{
  • "id": "entity123",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z",
  • "name": "string",
  • "enabled": true,
  • "settings": {
    }
}

Update history query item

Updates an existing item in a history query

path Parameters
historyId
required
string
itemId
required
string
Request Body schema: application/json
required
Any of
id
required
string or null
name
required
string
enabled
required
boolean
required
object (SouthADSItemSettings)

Responses

Request samples

Content type
application/json
Example
{
  • "id": "string",
  • "name": "string",
  • "enabled": true,
  • "settings": {
    }
}

Delete history query item

Delete a history query item

path Parameters
historyId
required
string
itemId
required
string

Responses

Create history query item

Creates a new item in a history query

path Parameters
historyId
required
string
Request Body schema: application/json
required
Any of
id
required
string or null
name
required
string
enabled
required
boolean
required
object (SouthADSItemSettings)

Responses

Request samples

Content type
application/json
Example
{
  • "id": "string",
  • "name": "string",
  • "enabled": true,
  • "settings": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": "entity123",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z",
  • "name": "string",
  • "enabled": true,
  • "settings": {
    }
}

Delete all items

Delete all items from a history query

path Parameters
historyId
required
string

Responses

Enable history query item

Enable a history query item

path Parameters
historyId
required
string
itemId
required
string

Responses

Disable history query item

Disable a history query item

path Parameters
historyId
required
string
itemId
required
string

Responses

Enable history query items

Enable a list of history query items

path Parameters
historyId
required
string
Request Body schema: application/json
required
itemIds
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "itemIds": [
    ]
}

Disable history query items

Disable a list of history query items

path Parameters
historyId
required
string
Request Body schema: application/json
required
itemIds
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "itemIds": [
    ]
}

Delete history query items

Delete a list of history query items

path Parameters
historyId
required
string
Request Body schema: application/json
required
itemIds
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "itemIds": [
    ]
}

Convert items to CSV

Converts frontend in memory items to CSV format

path Parameters
southType
required
string
Request Body schema: multipart/form-data
required
delimiter
required
string
items
required
string <binary>

Responses

Export items to CSV

Exports all items from a history query as a CSV file

path Parameters
historyId
required
string
Request Body schema: application/json
required
delimiter
required
string

CSV delimiter character

Responses

Request samples

Content type
application/json
{
  • "delimiter": "string"
}

Check CSV import

Validates a CSV file before import and checks for conflicts with existing items

path Parameters
southType
required
string
Request Body schema: multipart/form-data
required
delimiter
required
string
deleteItemsNotPresent
required
string
itemsToImport
required
string <binary>
currentItems
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "errors": [
    ]
}

Import items from CSV

Imports items from a CSV file into a history query

path Parameters
historyId
required
string
Request Body schema: multipart/form-data
required
items
required
string <binary>
deleteItemsNotPresent
required
string

Responses

Add/edit transformer

Adds or updates a transformer configuration for a history query

path Parameters
historyId
required
string
Request Body schema: application/json
required
id
required
string

The id used to match a transformer with options

required
Array of objects (ItemLightDTO)

The list of items associated to the transformer

required
CustomTransformerDTO (object) or StandardTransformerDTO (object) (TransformerDTO)

Union type representing either a custom or standard transformer.

options
required
object (Record_string.unknown_)

Construct a type with a set of properties K of type T

Responses

Request samples

Content type
application/json
{
  • "id": "id",
  • "items": [
    ],
  • "transformer": {
    },
  • "options": {
    }
}

Remove transformer

Remove a transformer from a history query

path Parameters
historyId
required
string
transformerId
required
string

Responses

Search files in cache, error and archive folders

Searches for files in the history query cache

path Parameters
historyId
required
string
query Parameters
nameContains
required
string
start
required
string
end
required
string
maxNumberOfFilesReturned
required
number <double>

Responses

Response samples

Content type
application/json
{
  • "searchDate": "2023-10-31T12:34:56.789Z",
  • "metrics": {
    },
  • "error": [
    ],
  • "archive": [
    ],
  • "cache": [
    ]
}

Retrieve cache file content

Retrieve a file from a north connector cache

path Parameters
historyId
required
string
filename
required
string
query Parameters
folder
required
string (DataFolderType)
Enum: "cache" "error" "archive"

Responses

Response samples

Content type
application/json
{
  • "content": "string",
  • "contentFilename": "string",
  • "contentType": "csv",
  • "truncated": true,
  • "totalSize": 0.1
}

Move or remove files from cache, error and archive folders

Update cache content by moving or removing files from cache, archive and error folders

path Parameters
historyId
required
string
Request Body schema: application/json
required
required
object
required
object
required
object

Responses

Request samples

Content type
application/json
{
  • "cache": {
    },
  • "error": {
    },
  • "archive": {
    }
}

Engine

Endpoints for managing the OIBus engine settings, metrics, and status

Retrieve engine configuration

Returns the current configuration settings of the OIBus engine

Responses

Response samples

Content type
application/json
{
  • "id": "entity123",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z",
  • "name": "OIBus OT",
  • "port": 2223,
  • "version": "3.7.0",
  • "launcherVersion": "3.7.0",
  • "proxyEnabled": false,
  • "proxyPort": null,
  • "logParameters": {
    }
}

Update engine configuration

Updates the configuration settings of the OIBus engine

Request Body schema: application/json
required
name
required
string

The name of the engine.

port
required
number <double>

The port on which the engine listens.

proxyEnabled
required
boolean

Whether the proxy is enabled.

proxyPort
required
number or null <double>

The port for the proxy, if enabled.

required
object

Logging parameters for different outputs.

Responses

Request samples

Content type
application/json
{
  • "name": "OIBus OT",
  • "port": 8080,
  • "proxyEnabled": false,
  • "proxyPort": null,
  • "logParameters": {
    }
}

Response samples

Content type
application/json
{
  • "needsRedirect": true,
  • "newPort": 3333
}

Reset metrics

Resets all metrics collected by the OIBus engine

Responses

Restart OIBus process

Restarts the OIBus process

Responses

Retrieve OIBus information

Returns version and system information about the OIBus instance

Responses

Response samples

Content type
application/json
{
  • "version": "3.7.0",
  • "launcherVersion": "3.7.0",
  • "oibusName": "OIBus OT",
  • "oibusId": "aBc12F",
  • "dataDirectory": "/var/lib/oibus",
  • "binaryDirectory": "/usr/lib/oibus",
  • "processId": "12345",
  • "hostname": "server1",
  • "operatingSystem": "linux",
  • "architecture": "x64",
  • "platform": "ubuntu"
}

Check OIBus status

Checks the current status of the OIBus engine

Responses

Content

Endpoints to add data into OIBus directly through the API

Inject a file into North connector cache(s) queue

Uploads a file and adds it to the specified North connector(s) cache. The file will be processed according to the North connector's configuration.

query Parameters
northId
required
string

One or more North connector IDs, comma-separated (e.g. id1,id2). The file is queued in every listed connector.

dataSourceId
required
string

An arbitrary identifier for the external source pushing the file. Used for tracing and logging.

Request Body schema: multipart/form-data
required
file
required
string <binary>

Responses

Inject any JSON content into North connector cache(s) queue

Adds any JSON content directly to the specified North connector(s) cache queue. The body can be any valid JSON object or array. It is serialized and wrapped as an OIBus any-content payload, allowing external systems to push arbitrary data directly into OIBus for further processing by North connectors.

query Parameters
northId
required
string

One or more North connector IDs, comma-separated (e.g. id1,id2). The content is queued in every listed connector.

dataSourceId
required
string

An arbitrary identifier for the external source pushing the content. Used for tracing and logging.

Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "property1": null,
  • "property2": null
}

IP Filters

Endpoints for managing IP filters used to control access to the system

List all IP filters

Retrieves a list of all IP filters

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create IP filter

Creates a new IP filter with the provided configuration

Request Body schema: application/json
required
address
required
string

A regex pattern matched against the remote client's IP address. A plain IP address (e.g. 192.168.1.1) is treated as a literal pattern. Use * to allow all addresses, or a regex prefix like 192\.168\. to allow an entire subnet. Both IPv4 and IPv6 addresses (including IPv4-mapped IPv6) are supported.

description
required
string

A description of the purpose or reason for this IP filter.

Responses

Request samples

Content type
application/json
{
  • "address": "192\\.168\\.1\\..*",
  • "description": "Allow traffic from the local admin workstation"
}

Response samples

Content type
application/json
{
  • "id": "entity123",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z",
  • "address": "192\\.168\\.1\\..*",
  • "description": "Allow traffic from the local admin workstation"
}

Get an IP filter

Retrieves a specific IP filter by its unique identifier

path Parameters
ipFilterId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "entity123",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z",
  • "address": "192\\.168\\.1\\..*",
  • "description": "Allow traffic from the local admin workstation"
}

Update IP filter

Updates an existing IP filter with new configuration

path Parameters
ipFilterId
required
string
Request Body schema: application/json
required
address
required
string

A regex pattern matched against the remote client's IP address. A plain IP address (e.g. 192.168.1.1) is treated as a literal pattern. Use * to allow all addresses, or a regex prefix like 192\.168\. to allow an entire subnet. Both IPv4 and IPv6 addresses (including IPv4-mapped IPv6) are supported.

description
required
string

A description of the purpose or reason for this IP filter.

Responses

Request samples

Content type
application/json
{
  • "address": "192\\.168\\.1\\..*",
  • "description": "Allow traffic from the local admin workstation"
}

Delete IP filter

Deletes an IP filter by its unique identifier

path Parameters
ipFilterId
required
string

Responses

Scan Modes

Endpoints for managing scan modes used to schedule data collection and processing

List all scan modes

Retrieves a list of all scan modes

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create scan mode

Creates a new scan mode with the provided configuration

Request Body schema: application/json
required
name
required
string

The name of the scan mode.

description
required
string

A description of the scan mode's purpose or behavior.

cron
required
string

A cron expression defining the scan schedule.

Responses

Request samples

Content type
application/json
{
  • "name": "Daily Backup Scan",
  • "description": "Scans for new backup data every day at midnight",
  • "cron": "0 0 * * *"
}

Response samples

Content type
application/json
{
  • "id": "entity123",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z",
  • "name": "Daily Backup Scan",
  • "description": "Scans for new backup data every day at midnight",
  • "cron": "0 0 * * *"
}

Get scan mode

Retrieves a specific scan mode by its unique identifier

path Parameters
scanModeId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "entity123",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z",
  • "name": "Daily Backup Scan",
  • "description": "Scans for new backup data every day at midnight",
  • "cron": "0 0 * * *"
}

Update scan mode

Updates an existing scan mode with new configuration

path Parameters
scanModeId
required
string
Request Body schema: application/json
required
name
required
string

The name of the scan mode.

description
required
string

A description of the scan mode's purpose or behavior.

cron
required
string

A cron expression defining the scan schedule.

Responses

Request samples

Content type
application/json
{
  • "name": "Daily Backup Scan",
  • "description": "Scans for new backup data every day at midnight",
  • "cron": "0 0 * * *"
}

Delete scan mode

Deletes a scan mode by its unique identifier

path Parameters
scanModeId
required
string

Responses

Validate cron expression

Validates a cron expression to ensure it's properly formatted

Request Body schema: application/json
required
cron
required
string

Responses

Request samples

Content type
application/json
{
  • "cron": "string"
}

Response samples

Content type
application/json
{
  • "isValid": true,
  • "errorMessage": "",
  • "nextExecutions": [
    ],
  • "humanReadableForm": "At 00:00 every day"
}

Certificates

Endpoints for managing SSL/TLS certificates used for secure communication

List all certificates

Retrieves a list of all available certificates

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create certificate

Creates a new certificate with the provided details

Request Body schema: application/json
required
name
required
string

The name of the certificate.

description
required
string

A description of the certificate's purpose or usage.

regenerateCertificate
required
boolean

Whether to regenerate the certificate.

required
object or null

Options for generating the certificate. Set to null to not regenerate certificate

Responses

Request samples

Content type
application/json
{
  • "name": "New Server SSL Certificate",
  • "description": "New SSL certificate for securing server communications",
  • "regenerateCertificate": false,
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "id": "entity123",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z",
  • "name": "Server SSL Certificate",
  • "description": "SSL certificate for securing server communications",
  • "publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
  • "certificate": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAKoK/heBjcOuMA0GCSqGSIb3DQEBBQUAMEUx...",
  • "expiry": "2023-10-31T12:34:56.789Z"
}

Get certificate by ID

Retrieves a specific certificate by its unique identifier

path Parameters
certificateId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "entity123",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z",
  • "name": "Server SSL Certificate",
  • "description": "SSL certificate for securing server communications",
  • "publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
  • "certificate": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAKoK/heBjcOuMA0GCSqGSIb3DQEBBQUAMEUx...",
  • "expiry": "2023-10-31T12:34:56.789Z"
}

Update certificate

Updates an existing certificate with new details

path Parameters
certificateId
required
string
Request Body schema: application/json
required
name
required
string

The name of the certificate.

description
required
string

A description of the certificate's purpose or usage.

regenerateCertificate
required
boolean

Whether to regenerate the certificate.

required
object or null

Options for generating the certificate. Set to null to not regenerate certificate

Responses

Request samples

Content type
application/json
{
  • "name": "New Server SSL Certificate",
  • "description": "New SSL certificate for securing server communications",
  • "regenerateCertificate": false,
  • "options": {
    }
}

Delete certificate

Deletes a certificate by its unique identifier

path Parameters
certificateId
required
string

Responses

Logs

Endpoints for searching and retrieving system logs

Search logs

Searches system logs with various filter parameters. If no time range is specified, defaults to the last 24 hours.

query Parameters
start
required
string (Instant)
Example: start=2023-10-31T12:34:56.789Z

ISO 8601 start of the time range (e.g. 2024-01-01T00:00:00.000Z). Defaults to 24 hours ago.

end
required
string (Instant)
Example: end=2023-10-31T12:34:56.789Z

ISO 8601 end of the time range (e.g. 2024-01-02T00:00:00.000Z). Defaults to now.

levels
required
string

Comma-separated list of log levels to include (e.g. error,warn). Valid values: silent, error, warn, info, debug, trace.

scopeIds
required
string

Comma-separated list of scope IDs to filter by (e.g. connector123,connector456).

scopeTypes
required
string

Comma-separated list of scope types to filter by (e.g. south,north). Valid values: south, north, history-query, internal, web-server.

messageContent
required
string

Substring to search for within log messages.

page
number <double>
Default: 0

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "totalElements": 2,
  • "size": 10,
  • "number": 0,
  • "totalPages": 1
}

Get scope suggestions

Returns a list of scope suggestions based on the provided name fragment

query Parameters
name
string
Default: ""

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get log scope details

Retrieves details for a specific log scope by its ID

path Parameters
scopeId
required
string

Responses

Response samples

Content type
application/json
{
  • "scopeId": "connector123",
  • "scopeName": "South Connector 1"
}

Users

Endpoints for managing user accounts and authentication

Search users

Searches for users with optional filtering by login name

query Parameters
login
required
string
page
required
number <double>

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "totalElements": 2,
  • "size": 10,
  • "number": 0,
  • "totalPages": 1
}

Create user

Creates a new user account with the provided details and password

Request Body schema: application/json
required
required
object (UserCommandDTO)

Command Data Transfer Object for creating or updating a user. Used as the request body for user creation/update endpoints.

password
required
string

Responses

Request samples

Content type
application/json
{
  • "user": {
    },
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "id": "entity123",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z",
  • "login": "john.doe",
  • "firstName": "John",
  • "lastName": "Doe",
  • "email": "john.doe@example.com",
  • "language": "en",
  • "timezone": "Europe/Paris",
  • "friendlyName": "John Doe"
}

Get user details

Retrieves a specific user by their unique identifier

path Parameters
userId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "entity123",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z",
  • "login": "john.doe",
  • "firstName": "John",
  • "lastName": "Doe",
  • "email": "john.doe@example.com",
  • "language": "en",
  • "timezone": "Europe/Paris",
  • "friendlyName": "John Doe"
}

Update user

Updates an existing user account with new details

path Parameters
userId
required
string
Request Body schema: application/json
required
login
required
string

The login username of the user.

firstName
required
string or null

The first name of the user. Can be null if not provided.

lastName
required
string or null

The last name of the user. Can be null if not provided.

email
required
string or null

The email address of the user. Can be null if not provided.

language
required
string (Language)
Enum: "fr" "en"

Type representing a supported language.

timezone
required
string (Timezone)

Represents a timezone as an IANA timezone string.

Responses

Request samples

Content type
application/json
{
  • "login": "john.doe",
  • "firstName": "John",
  • "lastName": "Doe",
  • "email": "john.doe@example.com",
  • "language": "en",
  • "timezone": "Europe/Paris"
}

Delete user

Deletes a user account by its unique identifier

path Parameters
userId
required
string

Responses

Change password

Updates a user's password

path Parameters
userId
required
string
Request Body schema: application/json
required
currentPassword
required
string

The current password of the user.

newPassword
required
string

The new password for the user.

Responses

Request samples

Content type
application/json
{
  • "currentPassword": "oldPassword123",
  • "newPassword": "newSecurePassword456"
}

OIAnalytics Registration

Endpoints for managing OIAnalytics service registration and connection settings

Retrieve registration settings

Returns the current OIAnalytics registration settings

Responses

Response samples

Content type
application/json
{
  • "id": "entity123",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z",
  • "host": "https://registration.example.com",
  • "activationCode": "ABC123",
  • "status": "NOT_REGISTERED",
  • "activationDate": "2023-10-31T12:34:56.789Z",
  • "activationExpirationDate": "2023-10-31T12:34:56.789Z",
  • "checkUrl": "https://instant.oianalytics.com/check",
  • "useProxy": false,
  • "proxyUrl": null,
  • "proxyUsername": null,
  • "useApiGateway": false,
  • "apiGatewayHeaderKey": null,
  • "apiGatewayBaseEndpoint": "string",
  • "acceptUnauthorized": false,
  • "commandRefreshInterval": 60,
  • "commandRetryInterval": 10,
  • "messageRetryInterval": 10,
  • "commandPermissions": {
    }
}

Update connection settings

Updates the connection settings for the OIAnalytics service

Request Body schema: application/json
required
host
required
string

The host URL for registration.

useProxy
required
boolean

Whether to use a proxy for registration.

proxyUrl
required
string or null

The proxy URL for registration.

proxyUsername
required
string or null

The username for proxy authentication.

proxyPassword
required
string or null

The password for proxy authentication.

useApiGateway
required
boolean

Whether to use an API Gateway

apiGatewayHeaderKey
required
string or null

The header key for the API gateway

apiGatewayHeaderValue
required
string or null

The header value (a secret) used for the API gateway

apiGatewayBaseEndpoint
required
string or null

The base endpoint used by the API gateway

acceptUnauthorized
required
boolean

Whether to accept unauthorized certificates.

commandRefreshInterval
required
number <double>

The interval in seconds for refreshing commands.

commandRetryInterval
required
number <double>

The interval in seconds for retrying commands.

messageRetryInterval
required
number <double>

The interval in seconds for retrying messages.

required
object

Permissions for various commands.

Responses

Request samples

Content type
application/json
{
  • "host": "https://instance.oianalytics.com",
  • "useProxy": false,
  • "proxyUrl": null,
  • "proxyUsername": null,
  • "proxyPassword": null,
  • "useApiGateway": false,
  • "apiGatewayHeaderKey": null,
  • "apiGatewayHeaderValue": null,
  • "apiGatewayBaseEndpoint": "string",
  • "acceptUnauthorized": false,
  • "commandRefreshInterval": 60,
  • "commandRetryInterval": 10,
  • "messageRetryInterval": 10,
  • "commandPermissions": {
    }
}

Register service

Registers the current instance of OIBus with the OIAnalytics service

Request Body schema: application/json
required
host
required
string

The host URL for registration.

useProxy
required
boolean

Whether to use a proxy for registration.

proxyUrl
required
string or null

The proxy URL for registration.

proxyUsername
required
string or null

The username for proxy authentication.

proxyPassword
required
string or null

The password for proxy authentication.

useApiGateway
required
boolean

Whether to use an API Gateway

apiGatewayHeaderKey
required
string or null

The header key for the API gateway

apiGatewayHeaderValue
required
string or null

The header value (a secret) used for the API gateway

apiGatewayBaseEndpoint
required
string or null

The base endpoint used by the API gateway

acceptUnauthorized
required
boolean

Whether to accept unauthorized certificates.

commandRefreshInterval
required
number <double>

The interval in seconds for refreshing commands.

commandRetryInterval
required
number <double>

The interval in seconds for retrying commands.

messageRetryInterval
required
number <double>

The interval in seconds for retrying messages.

required
object

Permissions for various commands.

Responses

Request samples

Content type
application/json
{
  • "host": "https://instance.oianalytics.com",
  • "useProxy": false,
  • "proxyUrl": null,
  • "proxyUsername": null,
  • "proxyPassword": null,
  • "useApiGateway": false,
  • "apiGatewayHeaderKey": null,
  • "apiGatewayHeaderValue": null,
  • "apiGatewayBaseEndpoint": "string",
  • "acceptUnauthorized": false,
  • "commandRefreshInterval": 60,
  • "commandRetryInterval": 10,
  • "messageRetryInterval": 10,
  • "commandPermissions": {
    }
}

Test connection

Test connection to OIAnalytics service with the provided settings

Request Body schema: application/json
required
host
required
string

The host URL for registration.

useProxy
required
boolean

Whether to use a proxy for registration.

proxyUrl
required
string or null

The proxy URL for registration.

proxyUsername
required
string or null

The username for proxy authentication.

proxyPassword
required
string or null

The password for proxy authentication.

useApiGateway
required
boolean

Whether to use an API Gateway

apiGatewayHeaderKey
required
string or null

The header key for the API gateway

apiGatewayHeaderValue
required
string or null

The header value (a secret) used for the API gateway

apiGatewayBaseEndpoint
required
string or null

The base endpoint used by the API gateway

acceptUnauthorized
required
boolean

Whether to accept unauthorized certificates.

commandRefreshInterval
required
number <double>

The interval in seconds for refreshing commands.

commandRetryInterval
required
number <double>

The interval in seconds for retrying commands.

messageRetryInterval
required
number <double>

The interval in seconds for retrying messages.

required
object

Permissions for various commands.

Responses

Request samples

Content type
application/json
{
  • "host": "https://instance.oianalytics.com",
  • "useProxy": false,
  • "proxyUrl": null,
  • "proxyUsername": null,
  • "proxyPassword": null,
  • "useApiGateway": false,
  • "apiGatewayHeaderKey": null,
  • "apiGatewayHeaderValue": null,
  • "apiGatewayBaseEndpoint": "string",
  • "acceptUnauthorized": false,
  • "commandRefreshInterval": 60,
  • "commandRetryInterval": 10,
  • "messageRetryInterval": 10,
  • "commandPermissions": {
    }
}

Unregister service

Unregister from OIAnalytics service. OIBus will still be registered on OIAnalytics. It must be removed manually

Responses

OIAnalytics Commands

Endpoints for managing OIAnalytics commands and their execution status

Search OIAnalytics commands

Searches OIAnalytics commands with optional filtering by type, status, and time range.

query Parameters
types
required
string

Comma-separated list of command types to filter by (e.g. update-version,restart-engine).

status
required
string

Comma-separated list of statuses to filter by (e.g. COMPLETED,ERRORED). Valid values: RETRIEVED, RUNNING, ERRORED, CANCELLED, COMPLETED.

start
required
string (Instant)
Example: start=2023-10-31T12:34:56.789Z

ISO 8601 start of the time range.

end
required
string (Instant)
Example: end=2023-10-31T12:34:56.789Z

ISO 8601 end of the time range.

ack
required
boolean

Filter by acknowledgement status. true returns only acknowledged commands.

page
number <double>
Default: 0

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "totalElements": 2,
  • "size": 10,
  • "number": 0,
  • "totalPages": 1
}

Delete OIAnalytics command

Deletes an OIAnalytics command by its unique identifier

path Parameters
commandId
required
string

Responses

Transformers

Endpoints for managing data transformers used to convert data between different formats

List all transformer types

Retrieves a list of all available transformer types

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get transformer manifest

Retrieves a specific transformer manifest by its type

path Parameters
type
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "csv-to-mqtt",
  • "inputType": "string",
  • "outputType": "string",
  • "settings": {
    }
}

Search transformers

Searches for transformers with optional filtering by type, input type, and output type

query Parameters
type
required
string
Enum: "standard" "custom"
inputType
required
string (OIBusDataType)
Enum: "any" "time-values" "setpoint"

Type representing an OIBus data type.

outputType
required
string (OIBusDataType)
Enum: "any" "time-values" "setpoint"

Type representing an OIBus data type.

page
number <double>
Default: 0

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "totalElements": 2,
  • "size": 10,
  • "number": 0,
  • "totalPages": 1
}

List all transformers

Retrieves a complete list of all available transformers

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get transformer by ID

Retrieves a specific transformer by its unique identifier

path Parameters
transformerId
required
string

Responses

Response samples

Content type
application/json
Example
{
  • "id": "transformer123",
  • "type": "custom",
  • "inputType": "string",
  • "outputType": "string",
  • "manifest": {
    },
  • "name": "String to Number",
  • "description": "Converts string input to numeric output",
  • "customCode": "function transform(input) { return parseFloat(input); }",
  • "language": "string",
  • "timeout": 2000,
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z"
}

Update transformer

Updates an existing custom transformer with new configuration

path Parameters
transformerId
required
string
Request Body schema: application/json
required
type
required
string
Value: "custom"

The type of the transformer (always 'custom' for this interface).

inputType
required
string

The input data type that the transformer accepts.

outputType
required
string

The output data type that the transformer produces.

name
required
string

The name of the custom transformer.

description
required
string

A description of what the custom transformer does.

customCode
required
string

The custom JavaScript code that implements the transformation logic.

required
object (OIBusObjectAttribute)

Object-type attribute that groups related attributes. Used to create nested form structures.

language
required
string (TransformerLanguage)
timeout
required
number <double>

The maximum execution time for the custom code in milliseconds.

Responses

Request samples

Content type
application/json
{
  • "type": "custom",
  • "inputType": "string",
  • "outputType": "number",
  • "name": "String to Number",
  • "description": "Converts string input to numeric output",
  • "customCode": "function transform(input) { return parseFloat(input); }",
  • "customManifest": {
    },
  • "language": "string",
  • "timeout": 2000
}

Delete transformer

Deletes a transformer by its unique identifier

path Parameters
transformerId
required
string

Responses

Create transformer

Creates a new data transformer with the provided configuration

Request Body schema: application/json
required
type
required
string
Value: "custom"

The type of the transformer (always 'custom' for this interface).

inputType
required
string

The input data type that the transformer accepts.

outputType
required
string

The output data type that the transformer produces.

name
required
string

The name of the custom transformer.

description
required
string

A description of what the custom transformer does.

customCode
required
string

The custom JavaScript code that implements the transformation logic.

required
object (OIBusObjectAttribute)

Object-type attribute that groups related attributes. Used to create nested form structures.

language
required
string (TransformerLanguage)
timeout
required
number <double>

The maximum execution time for the custom code in milliseconds.

Responses

Request samples

Content type
application/json
{
  • "type": "custom",
  • "inputType": "string",
  • "outputType": "number",
  • "name": "String to Number",
  • "description": "Converts string input to numeric output",
  • "customCode": "function transform(input) { return parseFloat(input); }",
  • "customManifest": {
    },
  • "language": "string",
  • "timeout": 2000
}

Response samples

Content type
application/json
{
  • "id": "transformer123",
  • "type": "custom",
  • "inputType": "string",
  • "outputType": "string",
  • "manifest": {
    },
  • "name": "String to Number",
  • "description": "Converts string input to numeric output",
  • "customCode": "function transform(input) { return parseFloat(input); }",
  • "language": "string",
  • "timeout": 2000,
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "createdAt": "2023-10-31T12:34:56.789Z",
  • "updatedAt": "2023-10-31T12:34:56.789Z"
}

Test a custom transformer

Runs a custom transformer against the provided input data and returns the transformed output. Use this endpoint to validate transformer logic before saving it.

Request Body schema: application/json
required
required
object (TransformerTestRequest)

Request payload for testing a custom transformer.

required
object (CustomTransformerCommandDTO)

Command Data Transfer Object for creating or updating a custom transformer.

Responses

Request samples

Content type
application/json
{
  • "testRequest": {
    },
  • "transformer": {
    }
}

Response samples

Content type
application/json
{
  • "output": "{\"topic\":\"sensors/sensor1\",\"payload\":42}",
  • "metadata": {
    }
}

Get input template for a transformer input type

Returns a sample input payload for the given input type, useful as a starting point when writing or testing a custom transformer.

path Parameters
inputType
required
string (InputType)

Responses

Response samples

Content type
application/json
{
  • "type": "string",
  • "data": "string",
  • "description": "string"
}