---
title: "Start south explore session"
method: POST
path: "/api/history/{historyId}/explore"
tags: ["History Queries"]
---

# Start south explore session

`POST /api/history/{historyId}/explore`

## Request

- Base URL: `http://localhost:2223`
- URL: `http://localhost:2223/api/history/{historyId}/explore`
- Auth: none required
- TypeScript: <https://skmtc.dev/optimistiksas/apis/oibus-api/docs/api/history/:historyId/explore/post.ts> (a function with typed inputs; its response is checked against the schema)

Start an interactive explore session for a history query's south connector

## Path parameters

- `historyId` string, required

## Query parameters

- `southType` 'opcua' | 'mqtt' | 'modbus' | 'oianalytics' | 'ads' | 'bacnet' | 'folder-scanner' | 'ftp' | 'influxdb' | 'mongodb' | 'mssql' | 'mysql' | 'odbc' | 'oledb' | 'opc' | 'oracle' | 'osisoft-pi' | 'postgresql' | 'rest' | 's7' | 'sftp' | 'sqlite', required: Type representing the possible types for a South connector.
- `fromSouth` string, required

## Request body

- union
  - SouthADSSettings
    - `netId` string, required
    - `port` number, double, required
    - `routerAddress` string, nullable, required
    - `routerTcpPort` number, double, nullable, required
    - `clientAmsNetId` string, nullable, required
    - `clientAdsPort` number, double, nullable, required
    - `retryInterval` number, double, required
    - `plcName` string, nullable, required
    - `enumAsText` 'text' | 'integer', required
    - `boolAsText` 'text' | 'integer', required
    - `structureFiltering` SouthADSSettingsStructureFiltering[], nullable, required
      - `name` string, required
      - `fields` string, required
  - SouthBACnetSettings
    - `port` number, double, required
    - `apduTimeout` number, double, required
    - `retryInterval` number, double, required
    - `discoveryMode` 'broadcast' | 'target-device' | 'router', required
    - `discoveryTargetAddress` string
    - `discoveryTargetDeviceInstance` number, double
    - `discoveryRouterAddress` string
    - `broadcastAddress` string
    - `localInterface` string, nullable, required
    - `maxParallelRun` number, double, required
    - `maxObjectsPerRequest` number, double, required
    - `covDefaultLifetime` number, double, required
    - `covRenewalMargin` number, double, required
    - `maxNumberOfMessages` number, double, required
    - `flushMessageTimeout` number, double, required
    - `bbmd` SouthBACnetSettingsBbmd, required
      - `enabled` boolean, required
      - `address` string
      - `foreignDeviceTtl` number, double
  - SouthFolderScannerSettings
    - `inputFolder` string, required
    - `username` string, nullable
    - `password` string, nullable
    - `domain` string, nullable
  - SouthFTPSettings
    - `host` string, required
    - `port` number, double, required
    - `authentication` 'none' | 'password', required
    - `username` string, nullable
    - `password` string, nullable
    - `retryInterval` number, double, required
  - SouthInfluxDBSettings
    - `connectionSettings` SouthInfluxDBSettingsConnectionSettings, required
      - `version` '1' | '2' | '3', required
      - `host` string
      - `port` number, double
      - `protocol` 'http' | 'https'
      - `database` string
      - `username` string, nullable
      - `password` string, nullable
      - `url` string
      - `token` string, nullable
      - `organisation` string
      - `bucket` string
    - `maxParallelRun` number, double, required
  - SouthModbusSettings
    - `host` string, required
    - `port` number, double, required
    - `connectTimeout` number, double, required
    - `networkTimeout` number, double, required
    - `retryInterval` number, double, required
    - `slaveId` number, double, required
    - `addressOffset` 'modbus' | 'jbus', required
    - `endianness` 'big-endian' | 'little-endian', required
    - `swapBytesInWords` boolean, required
    - `swapWordsInDWords` boolean, required
    - `batchQuery` boolean, required
    - `groupingGap` number, double
  - SouthMongoDBSettings
    - `connectionString` string, required
    - `connectionTimeout` number, double, required
    - `username` string, nullable, required
    - `password` string, nullable, required
  - SouthMQTTSettings
    - `url` string, required
    - `qos` '0' | '1' | '2', required
    - `persistent` boolean
    - `authentication` SouthMQTTSettingsAuthentication, required
      - `type` 'none' | 'basic' | 'cert', required
      - `username` string
      - `password` string, nullable
      - `certFilePath` string
      - `keyFilePath` string
      - `caFilePath` string
    - `rejectUnauthorized` boolean, required
    - `reconnectPeriod` number, double, required
    - `connectTimeout` number, double, required
    - `maxNumberOfMessages` number, double, required
    - `flushMessageTimeout` number, double, required
  - SouthMSSQLSettings
    - `connectionSettings` SouthMSSQLSettingsConnectionSettings, required
      - `host` string, required
      - `port` number, double, required
      - `connectionTimeout` number, double, required
      - `database` string, required
      - `encryption` boolean, required
      - `trustServerCertificate` boolean, required
      - `username` string, nullable, required
      - `password` string, nullable, required
      - `domain` string, nullable, required
      - `idleTimeout` number, double, required
    - `maxParallelRun` number, double, required
  - SouthMySQLSettings
    - `connectionSettings` SouthMySQLSettingsConnectionSettings, required
      - `host` string, required
      - `port` number, double, required
      - `connectionTimeout` number, double, required
      - `database` string, required
      - `username` string, nullable, required
      - `password` string, nullable, required
      - `idleTimeout` number, double, required
    - `maxParallelRun` number, double, required
  - SouthODBCSettings
    - `connectionTimeout` number, double, required
    - `connectionString` string, required
    - `password` string, nullable, required
    - `maxParallelRun` number, double, required
  - SouthOIAnalyticsSettings
    - `useOiaModule` boolean, required
    - `timeout` number, double, required
    - `specificSettings` SouthOIAnalyticsSettingsSpecificSettings
      - `host` string, required
      - `acceptUnauthorized` boolean, required
      - `authentication` 'basic' | 'aad-client-secret' | 'aad-certificate', required
      - `accessKey` string
      - `secretKey` string, nullable
      - `tenantId` string
      - `clientId` string
      - `clientSecret` string, nullable
      - `certificateId` string
      - `scope` string
      - `useProxy` boolean, required
      - `proxyUrl` string
      - `proxyUsername` string
      - `proxyPassword` string, nullable
  - SouthOLEDBSettings
    - `connectionTimeout` number, double, required
    - `retryInterval` number, double, required
    - `requestTimeout` number, double, required
    - `connectionString` string, required
    - `password` string, nullable, required
    - `maxParallelRun` number, double, required
  - SouthOPCSettings
    - `retryInterval` number, double, required
    - `host` string, required
    - `serverName` string, required
    - `mode` 'hda' | 'da', required
  - SouthOPCUASettings
    - `url` string, required
    - `keepSessionAlive` boolean, required
    - `connectionTimeout` number, double, required
    - `retryInterval` number, double, required
    - `securityMode` 'none' | 'sign' | 'sign-and-encrypt', required
    - `securityPolicy` 'none' | 'basic128' | 'basic192' | 'basic256' | 'basic128-rsa15' | 'basic192-rsa15' | 'basic256-rsa15' | 'basic256-sha256' | 'aes128-sha256-rsa-oaep' | 'pub-sub-aes-128-ctr' | 'pub-sub-aes-256-ctr'
    - `maxParallelRun` number, double, required
    - `readTimeout` number, double, required
    - `authentication` SouthOPCUASettingsAuthentication, required
      - `type` 'none' | 'basic' | 'cert', required
      - `username` string
      - `password` string, nullable
      - `certFilePath` string
      - `keyFilePath` string
    - `subscription` SouthOPCUASettingsSubscription, required
      - `publishingInterval` number, double, required
      - `maxKeepAliveCount` number, double, required
      - `numberOfMessageBeforeFlush` number, double, required
      - `delayBetweenFlush` number, double, required
  - SouthOracleSettings
    - `connectionSettings` SouthOracleSettingsConnectionSettings, required
      - `thickMode` boolean, required
      - `oracleClient` string
      - `host` string, required
      - `port` number, double, required
      - `connectionTimeout` number, double, required
      - `database` string, required
      - `username` string, nullable, required
      - `password` string, nullable, required
      - `idleTimeout` number, double, required
    - `maxParallelRun` number, double, required
  - SouthPISettings
    - `serverName` string, nullable, required
    - `retryInterval` number, double, required
  - SouthPostgreSQLSettings
    - `connectionSettings` SouthPostgreSQLSettingsConnectionSettings, required
      - `host` string, required
      - `port` number, double, required
      - `sslMode` boolean, required
      - `database` string, required
      - `connectionTimeout` number, double, required
      - `username` string, nullable, required
      - `password` string, nullable, required
      - `idleTimeout` number, double, required
    - `maxParallelRun` number, double, required
  - SouthRestSettings
    - `host` string, required
    - `acceptUnauthorized` boolean, required
    - `timeout` number, double, required
    - `authentication` SouthRestSettingsAuthentication, required
      - `type` 'none' | 'basic' | 'bearer' | 'api-key', required
      - `username` string
      - `password` string, nullable
      - `token` string, nullable
      - `apiKey` string
      - `apiValue` string, nullable
      - `addTo` 'header' | 'query-params'
    - `proxy` SouthRestSettingsProxy, required
      - `useProxy` boolean, required
      - `proxyUrl` string
      - `proxyUsername` string, nullable
      - `proxyPassword` string, nullable
    - `test` SouthRestSettingsTest, required
      - `method` 'GET' | 'POST' | 'PUT', required
      - `endpoint` string, required
      - `successCode` number, double, required
      - `body` string, nullable
  - SouthS7Settings
    - `host` string, required
    - `port` number, double, required
    - `connectionType` 'PG' | 'OP' | 'S7Basic', required
    - `rack` number, double, required
    - `slot` number, double, required
    - `connectTimeout` number, double, required
    - `requestTimeout` number, double, required
    - `retryInterval` number, double, required
  - SouthSFTPSettings
    - `host` string, required
    - `port` number, double, required
    - `authentication` 'password' | 'private-key', required
    - `username` string, required
    - `password` string, nullable
    - `privateKey` string
    - `passphrase` string, nullable
    - `retryInterval` number, double, required
  - SouthSQLiteSettings
    - `databasePath` string, required

## Response `200`

Ok

- SouthExploreStartResult: Result of starting an explore session.
  - `sessionId` string, required: Identifier of the stateful explore session, used for subsequent browse/close calls.
  - `entries` SouthConnectorExploreEntry[], required: The root-level entries of the data source.
    - `id` string, required: Stable identifier of the entry, passed back to expand it. OPC UA node id (e.g. "ns=1;s=Temperature") or a folder-relative path.
    - `name` string, required: Human-readable label (OPC UA display name or file/folder name).
    - `metadata` RecordStringStringOrNumber, required: Construct a type with a set of properties K of type T
    - `metadataKinds` PartialRecordStringSouthConnectorExploreFieldKind: Make all properties in T optional
    - `hasChildren` boolean, required: Whether the entry can be expanded to reveal children in the explore tree.

## Changes

- **2026-11-06** `f63635c622d6`: 1 breaking, 1 warning
  - added the new required request property `anyOf[#/components/schemas/SouthPISettings]/serverName`
  - removed the request property `anyOf[#/components/schemas/SouthPISettings]/agentUrl`
- **2026-11-04** `51e328f23f3b`: 1 breaking, 1 warning
  - added the new required request property `anyOf[#/components/schemas/SouthOLEDBSettings]/maxParallelRun`
  - removed the request property `anyOf[#/components/schemas/SouthOLEDBSettings]/agentUrl`
- **2026-11-04** `472aa9343c15`: 1 warning
  - removed the request property `anyOf[#/components/schemas/SouthOPCSettings]/agentUrl`
- **2026-11-03** `0d8fec570ce4`: 4 warning
  - removed the request property `anyOf[#/components/schemas/SouthODBCSettings]/agentUrl`
  - removed the request property `anyOf[#/components/schemas/SouthODBCSettings]/remoteAgent`
  - removed the request property `anyOf[#/components/schemas/SouthODBCSettings]/requestTimeout`
  - removed the request property `anyOf[#/components/schemas/SouthODBCSettings]/retryInterval`
- **2026-10-30** `15d2db93f8bb`: 2 warning
  - removed the request property `anyOf[#/components/schemas/SouthMSSQLSettings]/connectionSettings/requestTimeout`
  - removed the request property `anyOf[#/components/schemas/SouthPostgreSQLSettings]/connectionSettings/requestTimeout`

[Operation history](https://skmtc.dev/optimistiksas/apis/oibus-api/changes/api/history/:historyId/explore/post.md)

---

[API](https://skmtc.dev/optimistiksas/apis/oibus-api.md) - [All operations](https://skmtc.dev/optimistiksas/apis/oibus-api/llms.txt) - [OpenAPI document](https://skmtc.dev/optimistiksas/apis/oibus-api/revisions/553df74bab85?raw)