Data connector service#

Service for managing data connectors to external data sources.

OpenAPI file: nominal.data_connector.v1.json

Endpoints#

Batch get data connectors#

POST /data-connector/v1/batch-get

Gets the settings for a batch of data connectors. Connectors in workspaces the caller lacks workspace:view on are omitted rather than failing the call.

Body

dataConnectorRids array of string

At most 100 items.

Response

dataConnectors array of DataConnector

​

Fields of DataConnector
dataConnectorRid string

​

name string

​

description string

​

connectionDetails DataConnectorDetailsSecrets

​

Fields of DataConnectorDetailsSecrets
opcUa OpcUaConnectorDetailsSecret

​

Fields of OpcUaConnectorDetailsSecret
uri string

​

authenticationConfig OpcAuthenticationConfigSecret

​

Fields of OpcAuthenticationConfigSecret
one of anonymous, usernamePassword, token

​

anonymous object

​

usernamePassword OpcUsernamePasswordAuthenticationSecret

​

Fields of OpcUsernamePasswordAuthenticationSecret
username string

​

password string

​

token OpcTokenAuthenticationSecret

​

Fields of OpcTokenAuthenticationSecret
token string

​

scrapingConfig OpcUaScrapingConfig

​

Fields of OpcUaScrapingConfig
nodeExplorationConfig OpcUaNodeExplorationConfig

​

Fields of OpcUaNodeExplorationConfig
one of opcUaTraversalConfig, opcUaDirectNodeSubscription

​

opcUaTraversalConfig OpcUaTraversalConfig

​

Fields of OpcUaTraversalConfig
rootNodes array of OpcNode

Root nodes to start traversing for variable nodes. For each node specified here, we will recursively traverse child nodes until there are none left. If empty, defaults to starting from the objects folder node NodeId{ns=0;i=85}

Fields of OpcNode
namespace integer (int64)

​

identifier OpcIdentifierValue

​

Fields of OpcIdentifierValue
one of numeric, string

Request

curl -X POST "https://api.gov.nominal.io/api/data-connector/v1/batch-get" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "dataConnectorRids": [
    "<data connector rids>"
  ]
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/data-connector/v1/batch-get",
    headers={"Authorization": "Bearer <api key>"},
    json={"dataConnectorRids": ["<data connector rids>"]},
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/data-connector/v1/batch-get",
    headers={"Authorization": "Bearer <api key>"},
    json={"dataConnectorRids": ["<data connector rids>"]},
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/data-connector/v1/batch-get",
            headers={"Authorization": "Bearer <api key>"},
            json={"dataConnectorRids": ["<data connector rids>"]},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "dataConnectors": [
    {
      "dataConnectorRid": "<data connector rid>",
      "name": "<name>",
      "description": "<description>",
      "connectionDetails": {
        "opcUa": {
          "uri": "<uri>",
          "authenticationConfig": {
            "anonymous": {}
          },
          "scrapingConfig": {
            "nodeExplorationConfig": {
              "opcUaTraversalConfig": {
                "rootNodes": [
                  {
                    "namespace": 1,
                    "identifier": {
                      "numeric": 1
                    }
                  }
                ],
                "skipNodes": [
                  {
                    "namespace": 1,
                    "identifier": {
                      "numeric": 1
                    }
                  }
                ],
                "referenceExplorationType": "OPC_UA_REFERENCE_EXPLORATION_TYPE_ORGANIZES"
              }
            },
            "unitNodeName": "<unit node name>",
            "channelNamingConvention": {
              "nodeId": {}
            },
            "overrideHost": true,
            "unknownDataTypeHandling": "OPC_UA_UNKNOWN_DATA_TYPE_HANDLING_ERROR",
            "failedMonitorHandling": "OPC_UA_FAILED_MONITOR_HANDLING_ERROR",
            "timestampHandling": {
              "server": {}
            },
            "dataChangeFilter": {
              "trigger": "OPC_UA_DATA_CHANGE_TRIGGER_STATUS_ONLY",
              "deadbandType": "OPC_UA_DEADBAND_TYPE_NONE",
              "deadbandValue": 1
            },
            "dataAcquisitionConfig": {
              "subscription": {
                "failedMonitorHandling": "OPC_UA_FAILED_MONITOR_HANDLING_ERROR",
                "dataChangeFilter": {
                  "trigger": "OPC_UA_DATA_CHANGE_TRIGGER_STATUS_ONLY",
                  "deadbandType": "OPC_UA_DEADBAND_TYPE_NONE",
                  "deadbandValue": 1
                }
              }
            }
          }
        }
      },
      "workspaceRid": "<workspace rid>",
      "targetDatasetRid": "<target dataset rid>",
      "createdAt": "2026-01-01T00:00:00Z"
    }
  ]
}

Create data connector#

POST /data-connector/v1/connector

Creates a new data connector configuration

Body

name string required

​

description string

​

connectionDetails DataConnectorDetails required

​

Fields of DataConnectorDetails
opcUa OpcUaConnectorDetails

​

Fields of OpcUaConnectorDetails
uri string required

​

authenticationConfig OpcAuthenticationConfig required

​

Fields of OpcAuthenticationConfig
one of anonymous, usernamePassword, token required

​

anonymous object

​

usernamePassword OpcUsernamePasswordAuthentication

​

Fields of OpcUsernamePasswordAuthentication
username string required

​

password string required

​

token OpcTokenAuthentication

​

Fields of OpcTokenAuthentication
token string required

​

scrapingConfig OpcUaScrapingConfig required

​

Fields of OpcUaScrapingConfig
nodeExplorationConfig OpcUaNodeExplorationConfig required

​

Fields of OpcUaNodeExplorationConfig
one of opcUaTraversalConfig, opcUaDirectNodeSubscription required

​

opcUaTraversalConfig OpcUaTraversalConfig

​

Fields of OpcUaTraversalConfig
rootNodes array of OpcNode

Root nodes to start traversing for variable nodes. For each node specified here, we will recursively traverse child nodes until there are none left. If empty, defaults to starting from the objects folder node NodeId{ns=0;i=85}

Fields of OpcNode
namespace integer (int64)

​

identifier OpcIdentifierValue required

​

Fields of OpcIdentifierValue
one of numeric, string required

​

numeric integer

Request

curl -X POST "https://api.gov.nominal.io/api/data-connector/v1/connector" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "name": "<name>",
  "connectionDetails": {
    "opcUa": {
      "uri": "<uri>",
      "authenticationConfig": {
        "anonymous": {}
      },
      "scrapingConfig": {
        "nodeExplorationConfig": {
          "opcUaTraversalConfig": {
            "referenceExplorationType": "OPC_UA_REFERENCE_EXPLORATION_TYPE_ORGANIZES"
          }
        },
        "unitNodeName": "<unit node name>",
        "channelNamingConvention": {
          "nodeId": {}
        },
        "overrideHost": true,
        "unknownDataTypeHandling": "OPC_UA_UNKNOWN_DATA_TYPE_HANDLING_ERROR",
        "timestampHandling": {
          "server": {}
        }
      }
    }
  },
  "workspaceRid": "<workspace rid>",
  "targetDatasetRid": "<target dataset rid>"
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/data-connector/v1/connector",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "name": "<name>",
        "connectionDetails": {
            "opcUa": {
                "uri": "<uri>",
                "authenticationConfig": {"anonymous": {}},
                "scrapingConfig": {
                    "nodeExplorationConfig": {
                        "opcUaTraversalConfig": {
                            "referenceExplorationType": "OPC_UA_REFERENCE_EXPLORATION_TYPE_ORGANIZES",
                        },
                    },
                    "unitNodeName": "<unit node name>",
                    "channelNamingConvention": {"nodeId": {}},
                    "overrideHost": True,
                    "unknownDataTypeHandling": "OPC_UA_UNKNOWN_DATA_TYPE_HANDLING_ERROR",
                    "timestampHandling": {"server": {}},
                },
            },
        },
        "workspaceRid": "<workspace rid>",
        "targetDatasetRid": "<target dataset rid>",
    },
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/data-connector/v1/connector",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "name": "<name>",
        "connectionDetails": {
            "opcUa": {
                "uri": "<uri>",
                "authenticationConfig": {"anonymous": {}},
                "scrapingConfig": {
                    "nodeExplorationConfig": {
                        "opcUaTraversalConfig": {
                            "referenceExplorationType": "OPC_UA_REFERENCE_EXPLORATION_TYPE_ORGANIZES",
                        },
                    },
                    "unitNodeName": "<unit node name>",
                    "channelNamingConvention": {"nodeId": {}},
                    "overrideHost": True,
                    "unknownDataTypeHandling": "OPC_UA_UNKNOWN_DATA_TYPE_HANDLING_ERROR",
                    "timestampHandling": {"server": {}},
                },
            },
        },
        "workspaceRid": "<workspace rid>",
        "targetDatasetRid": "<target dataset rid>",
    },
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/data-connector/v1/connector",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "name": "<name>",
                "connectionDetails": {
                    "opcUa": {
                        "uri": "<uri>",
                        "authenticationConfig": {"anonymous": {}},
                        "scrapingConfig": {
                            "nodeExplorationConfig": {
                                "opcUaTraversalConfig": {
                                    "referenceExplorationType": "OPC_UA_REFERENCE_EXPLORATION_TYPE_ORGANIZES",
                                },
                            },
                            "unitNodeName": "<unit node name>",
                            "channelNamingConvention": {"nodeId": {}},
                            "overrideHost": True,
                            "unknownDataTypeHandling": "OPC_UA_UNKNOWN_DATA_TYPE_HANDLING_ERROR",
                            "timestampHandling": {"server": {}},
                        },
                    },
                },
                "workspaceRid": "<workspace rid>",
                "targetDatasetRid": "<target dataset rid>",
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "dataConnector": {
    "dataConnectorRid": "<data connector rid>",
    "name": "<name>",
    "description": "<description>",
    "connectionDetails": {
      "opcUa": {
        "uri": "<uri>",
        "authenticationConfig": {
          "anonymous": {}
        },
        "scrapingConfig": {
          "nodeExplorationConfig": {
            "opcUaTraversalConfig": {
              "rootNodes": [
                {
                  "namespace": 1,
                  "identifier": {
                    "numeric": 1
                  }
                }
              ],
              "skipNodes": [
                {
                  "namespace": 1,
                  "identifier": {
                    "numeric": 1
                  }
                }
              ],
              "referenceExplorationType": "OPC_UA_REFERENCE_EXPLORATION_TYPE_ORGANIZES"
            }
          },
          "unitNodeName": "<unit node name>",
          "channelNamingConvention": {
            "nodeId": {}
          },
          "overrideHost": true,
          "unknownDataTypeHandling": "OPC_UA_UNKNOWN_DATA_TYPE_HANDLING_ERROR",
          "failedMonitorHandling": "OPC_UA_FAILED_MONITOR_HANDLING_ERROR",
          "timestampHandling": {
            "server": {}
          },
          "dataChangeFilter": {
            "trigger": "OPC_UA_DATA_CHANGE_TRIGGER_STATUS_ONLY",
            "deadbandType": "OPC_UA_DEADBAND_TYPE_NONE",
            "deadbandValue": 1
          },
          "dataAcquisitionConfig": {
            "subscription": {
              "failedMonitorHandling": "OPC_UA_FAILED_MONITOR_HANDLING_ERROR",
              "dataChangeFilter": {
                "trigger": "OPC_UA_DATA_CHANGE_TRIGGER_STATUS_ONLY",
                "deadbandType": "OPC_UA_DEADBAND_TYPE_NONE",
                "deadbandValue": 1
              }
            }
          }
        }
      }
    },
    "workspaceRid": "<workspace rid>",
    "targetDatasetRid": "<target dataset rid>",
    "createdAt": "2026-01-01T00:00:00Z"
  }
}

Get data connector#

GET /data-connector/v1/{dataConnectorRid}

Gets the settings for a data connector

Path parameters

dataConnectorRid string required

​

Response

dataConnector DataConnector

​

Fields of DataConnector
dataConnectorRid string

​

name string

​

description string

​

connectionDetails DataConnectorDetailsSecrets

​

Fields of DataConnectorDetailsSecrets
opcUa OpcUaConnectorDetailsSecret

​

Fields of OpcUaConnectorDetailsSecret
uri string

​

authenticationConfig OpcAuthenticationConfigSecret

​

Fields of OpcAuthenticationConfigSecret
one of anonymous, usernamePassword, token

​

anonymous object

​

usernamePassword OpcUsernamePasswordAuthenticationSecret

​

Fields of OpcUsernamePasswordAuthenticationSecret
username string

​

password string

​

token OpcTokenAuthenticationSecret

​

Fields of OpcTokenAuthenticationSecret
token string

​

scrapingConfig OpcUaScrapingConfig

​

Fields of OpcUaScrapingConfig
nodeExplorationConfig OpcUaNodeExplorationConfig

​

Fields of OpcUaNodeExplorationConfig
one of opcUaTraversalConfig, opcUaDirectNodeSubscription

​

opcUaTraversalConfig OpcUaTraversalConfig

​

Fields of OpcUaTraversalConfig
rootNodes array of OpcNode

Root nodes to start traversing for variable nodes. For each node specified here, we will recursively traverse child nodes until there are none left. If empty, defaults to starting from the objects folder node NodeId{ns=0;i=85}

Fields of OpcNode
namespace integer (int64)

​

identifier OpcIdentifierValue

​

Fields of OpcIdentifierValue
one of numeric, string

Request

curl "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>" \
  -H "Authorization: Bearer <api key>"

import requests

response = requests.get(
    "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "dataConnector": {
    "dataConnectorRid": "<data connector rid>",
    "name": "<name>",
    "description": "<description>",
    "connectionDetails": {
      "opcUa": {
        "uri": "<uri>",
        "authenticationConfig": {
          "anonymous": {}
        },
        "scrapingConfig": {
          "nodeExplorationConfig": {
            "opcUaTraversalConfig": {
              "rootNodes": [
                {
                  "namespace": 1,
                  "identifier": {
                    "numeric": 1
                  }
                }
              ],
              "skipNodes": [
                {
                  "namespace": 1,
                  "identifier": {
                    "numeric": 1
                  }
                }
              ],
              "referenceExplorationType": "OPC_UA_REFERENCE_EXPLORATION_TYPE_ORGANIZES"
            }
          },
          "unitNodeName": "<unit node name>",
          "channelNamingConvention": {
            "nodeId": {}
          },
          "overrideHost": true,
          "unknownDataTypeHandling": "OPC_UA_UNKNOWN_DATA_TYPE_HANDLING_ERROR",
          "failedMonitorHandling": "OPC_UA_FAILED_MONITOR_HANDLING_ERROR",
          "timestampHandling": {
            "server": {}
          },
          "dataChangeFilter": {
            "trigger": "OPC_UA_DATA_CHANGE_TRIGGER_STATUS_ONLY",
            "deadbandType": "OPC_UA_DEADBAND_TYPE_NONE",
            "deadbandValue": 1
          },
          "dataAcquisitionConfig": {
            "subscription": {
              "failedMonitorHandling": "OPC_UA_FAILED_MONITOR_HANDLING_ERROR",
              "dataChangeFilter": {
                "trigger": "OPC_UA_DATA_CHANGE_TRIGGER_STATUS_ONLY",
                "deadbandType": "OPC_UA_DEADBAND_TYPE_NONE",
                "deadbandValue": 1
              }
            }
          }
        }
      }
    },
    "workspaceRid": "<workspace rid>",
    "targetDatasetRid": "<target dataset rid>",
    "createdAt": "2026-01-01T00:00:00Z"
  }
}

Delete data connector#

DELETE /data-connector/v1/{dataConnectorRid}

Deletes a data connector. This operation is idempotent.

Path parameters

dataConnectorRid string required

​

Response

An empty JSON object, {}.

Request

curl -X DELETE "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>" \
  -H "Authorization: Bearer <api key>"

import requests

response = requests.delete(
    "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.delete(
    "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.delete(
            "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{}

Update data connector#

POST /data-connector/v1/{dataConnectorRid}

Updates the settings for a data connector. body: "*" is required here. google.api.http routes fields outside the path and body to the query string, which has no spelling for a message field, so the body is the only place connection_details can travel — and it keeps connector credentials out of URLs, which proxy and CDN access logs retain.

Path parameters

dataConnectorRid string required

​

Body

name string

​

description string

​

connectionDetails DataConnectorDetailsUpdates

​

Fields of DataConnectorDetailsUpdates
opcUa OpcUaConnectorDetailsUpdates

​

Fields of OpcUaConnectorDetailsUpdates
uri string

​

authenticationConfig OpcAuthenticationConfig

​

Fields of OpcAuthenticationConfig
one of anonymous, usernamePassword, token required

​

anonymous object

​

usernamePassword OpcUsernamePasswordAuthentication

​

Fields of OpcUsernamePasswordAuthentication
username string required

​

password string required

​

token OpcTokenAuthentication

​

Fields of OpcTokenAuthentication
token string required

​

scrapingConfig OpcUaScrapingConfigUpdates

​

Fields of OpcUaScrapingConfigUpdates
nodeExplorationConfig OpcUaNodeExplorationConfig

​

Fields of OpcUaNodeExplorationConfig
one of opcUaTraversalConfig, opcUaDirectNodeSubscription required

​

opcUaTraversalConfig OpcUaTraversalConfig

​

Fields of OpcUaTraversalConfig
rootNodes array of OpcNode

Root nodes to start traversing for variable nodes. For each node specified here, we will recursively traverse child nodes until there are none left. If empty, defaults to starting from the objects folder node NodeId{ns=0;i=85}

Fields of OpcNode
namespace integer (int64)

​

identifier OpcIdentifierValue required

​

Fields of OpcIdentifierValue
one of numeric, string required

​

numeric integer

Request

curl -X POST "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "name": "<name>",
  "description": "<description>",
  "connectionDetails": {
    "opcUa": {
      "uri": "<uri>",
      "authenticationConfig": {
        "anonymous": {}
      },
      "scrapingConfig": {
        "nodeExplorationConfig": {
          "opcUaTraversalConfig": {
            "referenceExplorationType": "OPC_UA_REFERENCE_EXPLORATION_TYPE_ORGANIZES"
          }
        },
        "unitNodeName": "<unit node name>",
        "channelNamingConvention": {
          "nodeId": {}
        },
        "overrideHost": true,
        "unknownDataTypeHandling": "OPC_UA_UNKNOWN_DATA_TYPE_HANDLING_ERROR",
        "failedMonitorHandling": "OPC_UA_FAILED_MONITOR_HANDLING_ERROR",
        "timestampHandling": {
          "server": {}
        },
        "dataChangeFilter": {
          "trigger": "OPC_UA_DATA_CHANGE_TRIGGER_STATUS_ONLY",
          "deadbandType": "OPC_UA_DEADBAND_TYPE_NONE",
          "deadbandValue": 1
        },
        "dataAcquisitionConfig": {
          "subscription": {
            "failedMonitorHandling": "OPC_UA_FAILED_MONITOR_HANDLING_ERROR",
            "dataChangeFilter": {
              "trigger": "OPC_UA_DATA_CHANGE_TRIGGER_STATUS_ONLY",
              "deadbandType": "OPC_UA_DEADBAND_TYPE_NONE",
              "deadbandValue": 1
            }
          }
        }
      }
    }
  },
  "targetDatasetRid": "<target dataset rid>"
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "name": "<name>",
        "description": "<description>",
        "connectionDetails": {
            "opcUa": {
                "uri": "<uri>",
                "authenticationConfig": {"anonymous": {}},
                "scrapingConfig": {
                    "nodeExplorationConfig": {
                        "opcUaTraversalConfig": {
                            "referenceExplorationType": "OPC_UA_REFERENCE_EXPLORATION_TYPE_ORGANIZES",
                        },
                    },
                    "unitNodeName": "<unit node name>",
                    "channelNamingConvention": {"nodeId": {}},
                    "overrideHost": True,
                    "unknownDataTypeHandling": "OPC_UA_UNKNOWN_DATA_TYPE_HANDLING_ERROR",
                    "failedMonitorHandling": "OPC_UA_FAILED_MONITOR_HANDLING_ERROR",
                    "timestampHandling": {"server": {}},
                    "dataChangeFilter": {
                        "trigger": "OPC_UA_DATA_CHANGE_TRIGGER_STATUS_ONLY",
                        "deadbandType": "OPC_UA_DEADBAND_TYPE_NONE",
                        "deadbandValue": 1,
                    },
                    "dataAcquisitionConfig": {
                        "subscription": {
                            "failedMonitorHandling": "OPC_UA_FAILED_MONITOR_HANDLING_ERROR",
                            "dataChangeFilter": {
                                "trigger": "OPC_UA_DATA_CHANGE_TRIGGER_STATUS_ONLY",
                                "deadbandType": "OPC_UA_DEADBAND_TYPE_NONE",
                                "deadbandValue": 1,
                            },
                        },
                    },
                },
            },
        },
        "targetDatasetRid": "<target dataset rid>",
    },
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "name": "<name>",
        "description": "<description>",
        "connectionDetails": {
            "opcUa": {
                "uri": "<uri>",
                "authenticationConfig": {"anonymous": {}},
                "scrapingConfig": {
                    "nodeExplorationConfig": {
                        "opcUaTraversalConfig": {
                            "referenceExplorationType": "OPC_UA_REFERENCE_EXPLORATION_TYPE_ORGANIZES",
                        },
                    },
                    "unitNodeName": "<unit node name>",
                    "channelNamingConvention": {"nodeId": {}},
                    "overrideHost": True,
                    "unknownDataTypeHandling": "OPC_UA_UNKNOWN_DATA_TYPE_HANDLING_ERROR",
                    "failedMonitorHandling": "OPC_UA_FAILED_MONITOR_HANDLING_ERROR",
                    "timestampHandling": {"server": {}},
                    "dataChangeFilter": {
                        "trigger": "OPC_UA_DATA_CHANGE_TRIGGER_STATUS_ONLY",
                        "deadbandType": "OPC_UA_DEADBAND_TYPE_NONE",
                        "deadbandValue": 1,
                    },
                    "dataAcquisitionConfig": {
                        "subscription": {
                            "failedMonitorHandling": "OPC_UA_FAILED_MONITOR_HANDLING_ERROR",
                            "dataChangeFilter": {
                                "trigger": "OPC_UA_DATA_CHANGE_TRIGGER_STATUS_ONLY",
                                "deadbandType": "OPC_UA_DEADBAND_TYPE_NONE",
                                "deadbandValue": 1,
                            },
                        },
                    },
                },
            },
        },
        "targetDatasetRid": "<target dataset rid>",
    },
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "name": "<name>",
                "description": "<description>",
                "connectionDetails": {
                    "opcUa": {
                        "uri": "<uri>",
                        "authenticationConfig": {"anonymous": {}},
                        "scrapingConfig": {
                            "nodeExplorationConfig": {
                                "opcUaTraversalConfig": {
                                    "referenceExplorationType": "OPC_UA_REFERENCE_EXPLORATION_TYPE_ORGANIZES",
                                },
                            },
                            "unitNodeName": "<unit node name>",
                            "channelNamingConvention": {"nodeId": {}},
                            "overrideHost": True,
                            "unknownDataTypeHandling": "OPC_UA_UNKNOWN_DATA_TYPE_HANDLING_ERROR",
                            "failedMonitorHandling": "OPC_UA_FAILED_MONITOR_HANDLING_ERROR",
                            "timestampHandling": {"server": {}},
                            "dataChangeFilter": {
                                "trigger": "OPC_UA_DATA_CHANGE_TRIGGER_STATUS_ONLY",
                                "deadbandType": "OPC_UA_DEADBAND_TYPE_NONE",
                                "deadbandValue": 1,
                            },
                            "dataAcquisitionConfig": {
                                "subscription": {
                                    "failedMonitorHandling": "OPC_UA_FAILED_MONITOR_HANDLING_ERROR",
                                    "dataChangeFilter": {
                                        "trigger": "OPC_UA_DATA_CHANGE_TRIGGER_STATUS_ONLY",
                                        "deadbandType": "OPC_UA_DEADBAND_TYPE_NONE",
                                        "deadbandValue": 1,
                                    },
                                },
                            },
                        },
                    },
                },
                "targetDatasetRid": "<target dataset rid>",
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "dataConnector": {
    "dataConnectorRid": "<data connector rid>",
    "name": "<name>",
    "description": "<description>",
    "connectionDetails": {
      "opcUa": {
        "uri": "<uri>",
        "authenticationConfig": {
          "anonymous": {}
        },
        "scrapingConfig": {
          "nodeExplorationConfig": {
            "opcUaTraversalConfig": {
              "rootNodes": [
                {
                  "namespace": 1,
                  "identifier": {
                    "numeric": 1
                  }
                }
              ],
              "skipNodes": [
                {
                  "namespace": 1,
                  "identifier": {
                    "numeric": 1
                  }
                }
              ],
              "referenceExplorationType": "OPC_UA_REFERENCE_EXPLORATION_TYPE_ORGANIZES"
            }
          },
          "unitNodeName": "<unit node name>",
          "channelNamingConvention": {
            "nodeId": {}
          },
          "overrideHost": true,
          "unknownDataTypeHandling": "OPC_UA_UNKNOWN_DATA_TYPE_HANDLING_ERROR",
          "failedMonitorHandling": "OPC_UA_FAILED_MONITOR_HANDLING_ERROR",
          "timestampHandling": {
            "server": {}
          },
          "dataChangeFilter": {
            "trigger": "OPC_UA_DATA_CHANGE_TRIGGER_STATUS_ONLY",
            "deadbandType": "OPC_UA_DEADBAND_TYPE_NONE",
            "deadbandValue": 1
          },
          "dataAcquisitionConfig": {
            "subscription": {
              "failedMonitorHandling": "OPC_UA_FAILED_MONITOR_HANDLING_ERROR",
              "dataChangeFilter": {
                "trigger": "OPC_UA_DATA_CHANGE_TRIGGER_STATUS_ONLY",
                "deadbandType": "OPC_UA_DEADBAND_TYPE_NONE",
                "deadbandValue": 1
              }
            }
          }
        }
      }
    },
    "workspaceRid": "<workspace rid>",
    "targetDatasetRid": "<target dataset rid>",
    "createdAt": "2026-01-01T00:00:00Z"
  }
}

Get session status#

GET /data-connector/v1/{dataConnectorRid}/session

Gets the session status for a connection

Path parameters

dataConnectorRid string required

​

Response

one of none, active

​

none object

​

active ActiveSessionStatus

​

Fields of ActiveSessionStatus
replicaStatus array of ReplicaStatus

​

Values of ReplicaStatus
REPLICA_STATUS_UNSPECIFIED

​

REPLICA_STATUS_STARTING

​

REPLICA_STATUS_SUBSCRIBING

​

REPLICA_STATUS_RUNNING

​

REPLICA_STATUS_STOPPING

​

REPLICA_STATUS_STOPPED

​

Request

curl "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>/session" \
  -H "Authorization: Bearer <api key>"

import requests

response = requests.get(
    "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>/session",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>/session",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>/session",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "none": {}
}

Start session#

POST /data-connector/v1/{dataConnectorRid}/session/start

Starts a session for a connection

Path parameters

dataConnectorRid string required

​

Response

An empty JSON object, {}.

Request

curl -X POST "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>/session/start" \
  -H "Authorization: Bearer <api key>"

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>/session/start",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>/session/start",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>/session/start",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{}

Stop session#

POST /data-connector/v1/{dataConnectorRid}/session/stop

Stops a session for a connection

Path parameters

dataConnectorRid string required

​

Response

An empty JSON object, {}.

Request

curl -X POST "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>/session/stop" \
  -H "Authorization: Bearer <api key>"

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>/session/stop",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>/session/stop",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/data-connector/v1/<data connector rid>/session/stop",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{}

Errors#

Errors shows how these errors are sent.

Each error’s errorName is NominalDataConnectorV1: followed by its name below.

Status

Name

Notes

400

DataConnectorErrorTypeTargetDatasetNotInWorkspace

Data connector not found

403

DataConnectorErrorTypeConnectorNotAuthorized

Data connector not found

404

DataConnectorErrorTypeConnectorNotFound

Data connector not found

Types#

ActiveSessionStatus#

replicaStatus array of ReplicaStatus

​

DataConnector#

A configured data connector

dataConnectorRid string

​

name string

​

description string

​

connectionDetails DataConnectorDetailsSecrets

​

workspaceRid string

​

targetDatasetRid string

​

createdAt string (date-time)

​

DataConnectorDetails#

Union type for different data connector types

opcUa OpcUaConnectorDetails

​

DataConnectorDetailsSecrets#

Union type for different data connector types with secrets

opcUa OpcUaConnectorDetailsSecret

​

DataConnectorDetailsUpdates#

opcUa OpcUaConnectorDetailsUpdates

​

OpcAuthenticationConfig#

Authentication configuration for OPC-UA server connection

Set exactly one of the fields below.

one of anonymous, usernamePassword, token required

​

anonymous object

​

usernamePassword OpcUsernamePasswordAuthentication

​

token OpcTokenAuthentication

​

OpcAuthenticationConfigSecret#

Authentication configuration for OPC-UA server connection with secrets

Set exactly one of the fields below.

one of anonymous, usernamePassword, token required

​

anonymous object

​

usernamePassword OpcUsernamePasswordAuthenticationSecret

​

token OpcTokenAuthenticationSecret

​

OpcIdentifierValue#

The identifier field for an OPC-UA node

Set exactly one of the fields below.

one of numeric, string required

​

numeric integer

​

string string

​

OpcNode#

An OPC-UA node

namespace integer (int64)

​

identifier OpcIdentifierValue required

​

OpcTokenAuthentication#

token string required

​

OpcTokenAuthenticationSecret#

token string

​

OpcUaBrowseName#

An empty JSON object, {}.

OpcUaChannelNamingConvention#

How do you want to map the names of OPC-UA nodes to Nominal channels?

Set exactly one of the fields below.

one of nodeId, browseName, displayName, fullPath required

​

nodeId OpcUaNodeId

For example, “NodeId{ns=3;i=1010}”

browseName OpcUaBrowseName

The “name” field under the “BrowseName” attribute

displayName OpcUaDisplayName

The “text” field under the “DisplayName” attribute

fullPath OpcUaFullPath

The full path of the node, separated by a delimiter. Use this setting for creating the hierarchical prefix tree.

OpcUaConnectorDetails#

Configuration for connecting to an OPC-UA server

uri string required

​

authenticationConfig OpcAuthenticationConfig required

​

scrapingConfig OpcUaScrapingConfig required

​

OpcUaConnectorDetailsSecret#

Configuration for connecting to an OPC-UA server with secrets

uri string

​

authenticationConfig OpcAuthenticationConfigSecret

​

scrapingConfig OpcUaScrapingConfig

​

OpcUaConnectorDetailsUpdates#

Updated configuration for connecting to an OPC-UA server

uri string

​

authenticationConfig OpcAuthenticationConfig

​

scrapingConfig OpcUaScrapingConfigUpdates

​

OpcUaDataAcquisitionConfig#

Configuration for how data should be acquired from the OPC-UA server

Set at most one of the fields below.

one of subscription, polling

​

subscription OpcUaSubscriptionConfig

Use OPC-UA subscriptions to receive data changes pushed from the server

polling OpcUaPollingConfig

Periodically poll the server for current node values

OpcUaDataChangeFilter#

trigger OpcUaDataChangeTrigger

The trigger for the data change filter.

deadbandType OpcUaDeadbandType

​

deadbandValue number

​

OpcUaDataChangeTrigger#

OPC_UA_DATA_CHANGE_TRIGGER_UNSPECIFIED

​

OPC_UA_DATA_CHANGE_TRIGGER_STATUS_ONLY

​

OPC_UA_DATA_CHANGE_TRIGGER_STATUS_VALUE

​

OPC_UA_DATA_CHANGE_TRIGGER_STATUS_VALUE_TIMESTAMP

​

OpcUaDeadbandType#

OPC_UA_DEADBAND_TYPE_UNSPECIFIED

​

OPC_UA_DEADBAND_TYPE_NONE

​

OPC_UA_DEADBAND_TYPE_ABSOLUTE

​

OPC_UA_DEADBAND_TYPE_PERCENT

​

OpcUaDirectNodeSubscription#

nodes array of OpcNode

At least 1 item.

OpcUaDisplayName#

An empty JSON object, {}.

OpcUaFailedMonitorHandling#

OPC_UA_FAILED_MONITOR_HANDLING_UNSPECIFIED

​

OPC_UA_FAILED_MONITOR_HANDLING_ERROR

​

OPC_UA_FAILED_MONITOR_HANDLING_IGNORE

​

OpcUaFullPath#

Configuration for full path naming convention

rootNodes array of OpcNode

We will build path up to any of these nodes, or the Objects folder.

delimiter string

Custom delimiter for path separation. Defaults to “/” if not specified.

arrayTagNames array of string

Array TagNames to extract out of the path. For example, if the path is “/airplane/wing[1]/drag”, specifying the TagName “wing” would represent this with the channel “/airplane/drag” with “wing”:”1” as a tag.

OpcUaNodeExplorationConfig#

Set exactly one of the fields below.

one of opcUaTraversalConfig, opcUaDirectNodeSubscription required

​

opcUaTraversalConfig OpcUaTraversalConfig

​

opcUaDirectNodeSubscription OpcUaDirectNodeSubscription

​

OpcUaNodeId#

An empty JSON object, {}.

OpcUaPollingConfig#

Configuration for polling-based data acquisition

pollingIntervalMs string (uint64)

The interval between polls in milliseconds. Defaults to 1000ms if not specified.

OpcUaReferenceExplorationType#

OPC_UA_REFERENCE_EXPLORATION_TYPE_UNSPECIFIED

​

OPC_UA_REFERENCE_EXPLORATION_TYPE_ORGANIZES

​

OPC_UA_REFERENCE_EXPLORATION_TYPE_HIERARCHICAL_REFERENCES

​

OpcUaRelativeTimestamp#

Use the server timestamp, but add an optional offset. By default, the offset will be the time now. This is useful for when the server starts at an epoch time of 0.

offset string (date-time)

​

OpcUaScrapingConfig#

Configuration for determining how data is discovered and handled

Polling mode can only be used with server time.

nodeExplorationConfig OpcUaNodeExplorationConfig required

​

unitNodeName string required

The browse name of the node under which the unit is stored for the nodes we scrape.

channelNamingConvention OpcUaChannelNamingConvention required

​

overrideHost boolean required

If true, we will override the host and port of the OPC UA server with the host and port of the original server URL.

unknownDataTypeHandling OpcUaUnknownDataTypeHandling required

How we will handle unknown data types when we read them from the server

failedMonitorHandling OpcUaFailedMonitorHandling deprecated

Deprecated: Use data_acquisition_config.subscription.failed_monitor_handling instead.

timestampHandling OpcUaTimestampHandling required

What timestamps should we write for the channels?

dataChangeFilter OpcUaDataChangeFilter deprecated

Deprecated: Use data_acquisition_config.subscription.data_change_filter instead.

dataAcquisitionConfig OpcUaDataAcquisitionConfig

Configuration for how data should be acquired from the server. If not specified, defaults to subscription mode using the deprecated fields above.

OpcUaScrapingConfigUpdates#

Updated configuration for determining how data is discovered and handled

Polling mode can only be used with server time.

nodeExplorationConfig OpcUaNodeExplorationConfig

​

unitNodeName string

The browse name of the node under which the unit is stored for the nodes we scrape.

channelNamingConvention OpcUaChannelNamingConvention

​

overrideHost boolean

If true, we will override the host and port of the OPC UA server with the host and port of the original server URL.

unknownDataTypeHandling OpcUaUnknownDataTypeHandling

How we will handle unknown data types when we read them from the server

failedMonitorHandling OpcUaFailedMonitorHandling deprecated

Deprecated: Use data_acquisition_config.subscription.failed_monitor_handling instead.

timestampHandling OpcUaTimestampHandling

What timestamps should we write for the channels?

dataChangeFilter OpcUaDataChangeFilter deprecated

Deprecated: Use data_acquisition_config.subscription.data_change_filter instead.

dataAcquisitionConfig OpcUaDataAcquisitionConfig

Configuration for how data should be acquired from the server.

OpcUaServerTime#

Use the server timestamp https://reference.opcfoundation.org/Core/Part4/v104/docs/7.7.4

An empty JSON object, {}.

OpcUaSourceTime#

Use the source timestamp https://reference.opcfoundation.org/Core/Part4/v104/docs/7.7.3

An empty JSON object, {}.

OpcUaSubscriptionConfig#

Configuration for subscription-based data acquisition

failedMonitorHandling OpcUaFailedMonitorHandling required

How to handle situations where there are failed monitors.

dataChangeFilter OpcUaDataChangeFilter required

The data change filter to be applied for the monitored items in the subscription.

OpcUaTimestampHandling#

Set exactly one of the fields below.

one of server, source, relative required

​

server OpcUaServerTime

​

source OpcUaSourceTime

​

relative OpcUaRelativeTimestamp

​

OpcUaTraversalConfig#

rootNodes array of OpcNode

Root nodes to start traversing for variable nodes. For each node specified here, we will recursively traverse child nodes until there are none left. If empty, defaults to starting from the objects folder node NodeId{ns=0;i=85}

skipNodes array of OpcNode

We will not subscribe to any of these nodes.

referenceExplorationType OpcUaReferenceExplorationType required

The type of references that we will follow when traversing the root nodes in the OPC UA server.

OpcUaUnknownDataTypeHandling#

OPC_UA_UNKNOWN_DATA_TYPE_HANDLING_UNSPECIFIED

​

OPC_UA_UNKNOWN_DATA_TYPE_HANDLING_ERROR

If we encounter an unknown data type, we will error out

OPC_UA_UNKNOWN_DATA_TYPE_HANDLING_TREAT_AS_DOUBLE

If we encounter an unknown data type, we will assume it is a double

OPC_UA_UNKNOWN_DATA_TYPE_HANDLING_TREAT_AS_STRING

If we encounter an unknown data type, we will assume it is a string

OpcUsernamePasswordAuthentication#

username string required

​

password string required

​

OpcUsernamePasswordAuthenticationSecret#

username string required

​

password string

​

ReplicaStatus#

REPLICA_STATUS_UNSPECIFIED

​

REPLICA_STATUS_STARTING

​

REPLICA_STATUS_SUBSCRIBING

​

REPLICA_STATUS_RUNNING

​

REPLICA_STATUS_STOPPING

​

REPLICA_STATUS_STOPPED

​

Page design based on Scalar, MIT License.