Version: V3.2

UNS Read API

Read endpoints for the Unified Namespace (UNS) on the v2 Data API. These let an integrator browse the UNS tree (namespaces → assets → variables) and query values — latest value, raw history, and aggregated history — without any knowledge of the underlying store.

This is the UNS counterpart of the Raw time series Read API: where that API queries raw measurements by database/retentionPolicy/measurement, this one works against the modelled UNS hierarchy and addresses data by identifier (Guid).

info

UNS must be enabled for your company. Calls against a company without UNS enabled return 400.

info

Unlike the Raw time series Read API (which uses epoch milliseconds), all timestamps here — both the from/to query parameters and the timestamps in responses — are ISO 8601, UTC (e.g. 2026-06-29T08:00:00Z).

Headers

Every endpoint is a GET under https://portal.captureplatform.com and shares the headers below.

Header	Value
AuthVersion	`V0.0.1` (only value accepted; others return `401`)
Authorization	`[Bearer / ApiToken] <Received auth token>`
companyView	(Optional) restricts the call to a specific company view

tip

The caller needs the Data Explorer → View right on the company that owns the UNS. Missing rights return 403.

See Authentication for how to obtain a token.

How addressing works

The UNS is a tree of assets (enterprise, site, area, line, workCell, …) with variables at the leaves. Every node — asset or variable — has a stable id (Guid, the identifier) and a path.

To read a single signal, you need a variable.
To read everything beneath a level (a whole line, area, site, …), you address an asset.

Every value-read endpoint comes in two forms, addressing the same node either way:

By id — …/{id} in the route, where {id} is the node's Guid identifier. Best after you've browsed and cached ids.
By path — …/by-path/…?path=<ltree path>, where the path is the dot-separated UNS path (e.g. Vintecc.Site.Area.Line1.Temperature). Best when you already know the namespace layout and want to skip the id lookup. See Querying by UNS path.

The typical integration flow is: browse to discover nodes → read latest/history/aggregate by id or by path.

Endpoints at a glance

Path	Purpose
`/v2/uns/namespaces`	List top-level namespaces (browse entry point)
`/v2/uns/assets/{id}/children`	List child assets of an asset (paged)
`/v2/uns/assets/{id}/variables`	List child variables of an asset (paged)
`/v2/uns/assets/{id}`	Get a single asset's details
`/v2/uns/variables/{id}`	Get a single variable's details (incl. last value)
`/v2/uns/variables`	List/search variables (paged)
`/v2/uns/tree`	Export a full subtree as nested JSON
`/v2/uns/data/search`	Search identifiers by name/type
`/v2/uns/data/assets/{id}/tree`	Nested tree under an asset
`/v2/uns/data/assets/{id}/latest`	Latest value of every variable under an asset
`/v2/uns/data/variables/{id}`	Raw history of one variable
`/v2/uns/data/assets/{id}/datapoints`	Raw history of every variable under an asset
`/v2/uns/data/variables/{id}/aggregate`	Aggregated (bucketed) history of one variable

tip

Every /v2/uns/data/... value-read endpoint also has a by-path twin (.../by-path/...?path=), plus two path-only endpoints (variable schema and measurements). See Querying by UNS path.

Browsing the tree

Pagination

Browse endpoints are page-based. Two query parameters control paging:

Parameter	Reason
`pageSize` (Optional)	Items per page. Min `1` (default: `50`).
`currentPage` (Optional)	1-indexed page number. Min `1` (default: `1`).

The response wraps the items in a paging envelope:

{
  "pagingInfo": {
    "currentPage": 1,
    "pageSize": 50,
    "totalItems": 134,
    "totalPages": 3
  },
  "items": [ ... ]
}

List Namespaces

GET /v2/uns/namespaces

The entry point for browsing. Returns the top-level namespaces (one per company root) you have access to.

{
  "pagingInfo": { "currentPage": 1, "pageSize": 50, "totalItems": 1, "totalPages": 1 },
  "items": [
    {
      "id": "3f1c…",
      "name": "Vintecc",
      "companyId": 42,
      "hasChildren": true,
      "retentions": [
        { "databaseName": "vintecc", "databaseId": 7, "retentionName": "oneYear", "retentionId": 3 }
      ]
    }
  ]
}

List Child Assets / Child Variables

GET /v2/uns/assets/{id}/children — child assets of an asset. GET /v2/uns/assets/{id}/variables — child variables of an asset.

Both are paged (see Pagination) and return lightweight navigation nodes — ideal for lazily expanding a tree node by node.

{
  "pagingInfo": { "currentPage": 1, "pageSize": 50, "totalItems": 4, "totalPages": 1 },
  "items": [
    {
      "id": "8b2e…",
      "name": "Line 1",
      "type": "Asset",
      "hasChildren": true,
      "typeId": "…",
      "linkedUnsAssetIdChains": null,
      "subscriptionPaths": {
        "signalR": "…",
        "mqtt": "v1/uns/Vintecc/Site/Area/Line1"
      }
    }
  ]
}

Field	Type	Notes
`id`	string	Identifier of the node (use it as `{id}` in subsequent calls).
`name`	string	Display name.
`type`	string	`Asset`, `Variable`, `Gateway`, `ConnectionTag`, `Measurement`, or `Field`.
`hasChildren`	bool	Whether the node can be expanded further.
`subscriptionPaths.mqtt`	string	MQTT topic to subscribe to for live values (see the MQTT live-data docs).
`subscriptionPaths.signalR`	string	SignalR path for live values.

Get a Single Asset

GET /v2/uns/assets/{id}

Returns the asset's metadata, and (when present) its nested child assets and variables.

{
  "id": "8b2e…",
  "name": "Line 1",
  "companyId": 42,
  "description": null,
  "parentId": "1a0d…",
  "typeId": "…",
  "retentionIds": [3],
  "assets": null,
  "variables": null,
  "unsPath": "Vintecc.Site.Area.Line1",
  "toplevel": false
}

Get a Single Variable

GET /v2/uns/variables/{id}

Returns the variable's details including its last known value in lastValue — a convenient one-shot "latest value for a single signal".

{
  "id": "c91a…",
  "assetId": "8b2e…",
  "description": "Motor temperature",
  "name": "Temperature",
  "unit": "°C",
  "variableTypeId": 1,
  "dataTypeId": 2,
  "sourcePath": "42/abc/tag/Measurement/Field",
  "sourceMqttPath": "…",
  "assetPath": "Vintecc.Site.Area.Line1",
  "assetMqttPath": "v1/uns/Vintecc/Site/Area/Line1",
  "lastValue": {
    "value": 23.5,
    "tags": { },
    "utcTimestamp": "2026-06-29T08:00:00Z"
  },
  "unsPath": "Vintecc.Site.Area.Line1.Temperature",
  "unsMqttPath": "v1/uns/Vintecc/Site/Area/Line1/Temperature",
  "signalRPath": "…"
}

info

lastValue.value is dynamic — it can be a number, string, or boolean depending on the variable's data type. It is null when the variable has never received a value.

Search / List Variables

GET /v2/uns/variables

Paged list of variables, with an optional name filter. Same item shape as Get a Single Variable.

Parameter	Reason
`search` (Optional)	Case-insensitive filter on variable name.
`pageSize` (Optional)	Items per page (default: `50`).
`currentPage` (Optional)	1-indexed page number (default: `1`).

Search Identifiers (assets & variables)

GET /v2/uns/data/search

Search the whole tenant for assets or variables by name, optionally filtered by type. Returns a flat list (no paging envelope).

Parameter	Reason
`name`	Name to search for. Required.
`type` (Optional)	Filter by node type: `enterprise`, `site`, `area`, `line`, `workCell`, or `variable`.
`limit` (Optional)	Max results. `1..500` (default: `100`).
`offset` (Optional)	Rows to skip (default: `0`, min `0`).

[
  {
    "id": "c91a…",
    "path": "Vintecc.Site.Area.Line1.Temperature",
    "name": "Temperature",
    "type": "variable",
    "unit": "°C",
    "description": "Motor temperature"
  }
]

Export a Subtree

GET /v2/uns/tree

Returns a full nested export of the tree (or a subtree), including metadata. Useful for backups or one-shot syncs rather than interactive browsing.

Parameter	Reason
`rootPath` (Optional)	Path to start the export from. Defaults to the company root.

{
  "id": "1a0d…",
  "name": "Vintecc",
  "type": "enterprise",
  "metadata": { },
  "children": [
    {
      "id": "8b2e…",
      "name": "Line 1",
      "type": "line",
      "children": [],
      "variables": [
        { "id": "c91a…", "name": "Temperature", "type": "variable", "unit": "°C", "sourcePath": "…", "metadata": {}, "children": [], "variables": [] }
      ]
    }
  ],
  "variables": []
}

tip

For interactive UIs prefer the paged children/variables endpoints (lazy expansion). Use /v2/uns/tree or /v2/uns/data/assets/{id}/tree when you want a whole subtree in one response.

Nested Tree Under an Asset

GET /v2/uns/data/assets/{id}/tree

Returns the asset and all descendants recursively nested under children. Lighter than the export above (no metadata), and depth-limitable.

Parameter	Reason
`maxDepth` (Optional)	Limit how many levels deep to recurse (default: unlimited).

{
  "id": "8b2e…",
  "path": "Vintecc.Site.Area.Line1",
  "name": "Line 1",
  "type": "line",
  "unit": null,
  "description": null,
  "children": [
    { "id": "c91a…", "path": "Vintecc.Site.Area.Line1.Temperature", "name": "Temperature", "type": "variable", "unit": "°C", "description": null, "children": [] }
  ]
}

Reading values

Latest Value Under an Asset

GET /v2/uns/data/assets/{id}/latest

Returns the most recent value of every variable recursively beneath the given asset. Pass a site, area, line, workCell, … id to snapshot a whole branch in one call.

[
  {
    "identifierId": "c91a…",
    "path": "Vintecc.Site.Area.Line1.Temperature",
    "unit": "°C",
    "time": "2026-06-29T08:00:00Z",
    "value": 23.5,
    "strValue": null
  }
]

Field	Type	Notes
`value`	number \| null	Set for numeric variables.
`strValue`	string \| null	Set for string variables (numeric variables leave it `null`).
`time`	string \| null	Timestamp of the latest value; `null` if the variable has none.

tip

For the latest value of a single variable, GET /v2/uns/variables/{id} already returns lastValue — no separate call needed.

Raw History of One Variable

GET /v2/uns/data/variables/{id}

Parameter	Reason
`from`	Start of window, ISO 8601 UTC. Must be `< to`.
`to`	End of window, ISO 8601 UTC.
`limit` (Optional)	Max datapoints. `1..10000` (default: `1000`).
`offset` (Optional)	Datapoints to skip (default: `0`, min `0`).

{
  "identifierId": "c91a…",
  "path": "Vintecc.Site.Area.Line1.Temperature",
  "unit": "°C",
  "datapoints": [
    { "time": "2026-06-29T08:00:00Z", "value": 23.5, "strValue": null },
    { "time": "2026-06-29T08:00:10Z", "value": 23.7, "strValue": null }
  ]
}

Raw History Under an Asset

GET /v2/uns/data/assets/{id}/datapoints

Same parameters as above (from, to, limit, offset). Returns datapoints for every variable beneath the asset as a flat list, each row carrying its identifierId and path.

[
  { "identifierId": "c91a…", "path": "Vintecc.Site.Area.Line1.Temperature", "unit": "°C", "time": "2026-06-29T08:00:00Z", "value": 23.5, "strValue": null },
  { "identifierId": "d72b…", "path": "Vintecc.Site.Area.Line1.Pressure",    "unit": "bar", "time": "2026-06-29T08:00:00Z", "value": 1.2,  "strValue": null }
]

info

limit applies per request, not per variable. For dense windows or wide subtrees, page with offset or narrow from/to — see Pagination guidance.

Aggregated History of One Variable

GET /v2/uns/data/variables/{id}/aggregate

Returns numeric history bucketed into fixed intervals, with avg/min/max/count per bucket. Ideal for charts and downsampling long ranges.

Parameter	Reason
`from`	Start of window, ISO 8601 UTC. Must be `< to`.
`to`	End of window, ISO 8601 UTC.
`interval`	Bucket size. One of `1m`, `5m`, `15m`, `1h`, `6h`, `1d`. Required.

[
  { "bucket": "2026-06-29T08:00:00Z", "avg": 23.6, "min": 23.5, "max": 23.7, "count": 6 },
  { "bucket": "2026-06-29T08:01:00Z", "avg": 24.1, "min": 23.9, "max": 24.4, "count": 6 }
]

Field	Type	Notes
`bucket`	string	Start of the interval (ISO 8601 UTC).
`avg`	number \| null	Average of values in the bucket.
`min`	number \| null	Minimum value in the bucket.
`max`	number \| null	Maximum value in the bucket.
`count`	integer	Number of datapoints in the bucket.

info

Aggregation operates on numeric values. The fixed avg/min/max/count set is the only aggregation offered; there is no custom function or arbitrary interval.

Querying by UNS path

Every value-read endpoint above can also be addressed by UNS path instead of id, so integrators that already know the namespace layout can skip resolving ids first. The path is supplied as a path query parameter; everything else (other query parameters, headers, response shapes, auth) is identical to the id-based twin.

The `path` parameter

path is the node's ltree path: dot-separated segments, each matching [A-Za-z0-9_] (e.g. Vintecc.Site.Area.Line1.Temperature). It is the same value returned in the path/unsPath fields elsewhere in this API.

Status	When
`422`	`path` is empty or contains invalid characters (a segment not matching `[A-Za-z0-9_]`, or bad separators).
`404`	The path resolves to no node within your company's UNS, or (for variable endpoints) the node is not a variable.

tip

URL-encode the path value. The dots between segments are literal path separators — don't encode those, but do encode any reserved characters that might appear in a segment.

By-path equivalents

By-path endpoint	Same as (by id)	Returns
`GET /v2/uns/data/variables/by-path/datapoints`	`…/variables/{id}`	Raw history of one variable
`GET /v2/uns/data/variables/by-path/aggregate`	`…/variables/{id}/aggregate`	Aggregated history
`GET /v2/uns/data/assets/by-path/latest`	`…/assets/{id}/latest`	Latest value under an asset
`GET /v2/uns/data/assets/by-path/datapoints`	`…/assets/{id}/datapoints`	Raw history under an asset
`GET /v2/uns/data/assets/by-path/tree`	`…/assets/{id}/tree`	Nested tree under an asset

These take the same query parameters as their id twins (from/to/limit/offset for history, interval for aggregate, maxDepth for tree) plus the required path, and return the identical response bodies.

# Raw history of a variable, addressed by path
curl -sG "https://portal.captureplatform.com/v2/uns/data/variables/by-path/datapoints" \
  -H "AuthVersion: V0.0.1" \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "path=Vintecc.Site.Area.Line1.Temperature" \
  --data-urlencode "from=2026-06-29T00:00:00Z" \
  --data-urlencode "to=2026-06-29T23:59:59Z"

Variable Schema (path only)

GET /v2/uns/data/variables/by-path/schema?path=<variable path>

Returns the full schema for a single variable — unit, description, source bindings and metadata — without any values. There is no id-based equivalent.

{
  "id": "c91a…",
  "path": "Vintecc.Site.Area.Line1.Temperature",
  "name": "Temperature",
  "type": "variable",
  "unit": "°C",
  "description": "Motor temperature",
  "source": {
    "companyId": 42,
    "activationUid": "abc",
    "connectionTag": "tag",
    "measurement": "Measurement",
    "field": "Field"
  },
  "metadata": { "iso95Level": "workCell" }
}

Field	Type	Notes
`source`	object \| null	Where the variable is fed from (the originating connection/measurement/field); `null` for unbound variables.
`metadata`	object	Key/value metadata attached to the variable (may be empty).

Measurements Under an Asset (path only)

GET /v2/uns/data/assets/by-path/measurements?path=<asset path>

Lists every variable recursively beneath an asset, each with its full schema (the same shape as Variable Schema). Use it to enumerate everything you can read under a branch in one paginated call.

Parameter	Reason
`path`	Asset ltree path. Required.
`limit` (Optional)	Max variables per page. (default: `100`).
`offset` (Optional)	Variables to skip (default: `0`, min `0`).

{
  "path": "Vintecc.Site.Area.Line1",
  "totalCount": 2,
  "hasMore": false,
  "measurements": [
    {
      "id": "c91a…",
      "path": "Vintecc.Site.Area.Line1.Temperature",
      "name": "Temperature",
      "unit": "°C",
      "description": "Motor temperature",
      "source": { "companyId": 42, "activationUid": "abc", "connectionTag": "tag", "measurement": "Measurement", "field": "Field" },
      "metadata": { }
    }
  ]
}

Field	Type	Notes
`totalCount`	integer	Total number of variables under the asset (across all pages).
`hasMore`	bool	`true` when more pages remain after this `limit`/`offset`.

Pagination guidance for history

The raw-history endpoints (/data/variables/{id} and /data/assets/{id}/datapoints) cap each request at limit rows (max 10000). For large pulls:

Prefer narrow from/to windows over deep offsets — offset paging grows more expensive the further you skip.
For long ranges you only need to chart, use the aggregate endpoint to downsample server-side instead of pulling every raw point.
Historical data is immutable, so re-requesting a completed window is idempotent.

The same time-window chunking recipe described in the Raw time series Read API applies here.

Error Responses

The body is a plain message string.

Status	When
`400`	Validation failed (`from >= to`, `limit` out of range, invalid `interval`/`type`, empty `name`), or UNS is not enabled for the company.
`401`	`AuthVersion` is not `V0.0.1`, or the token is missing/invalid/expired.
`403`	Valid token but missing Data Explorer → View on the owning company.
`404`	The `id` or `path` does not exist or is not within your company's UNS (asset/variable/path not found).
`422`	`path` is empty or malformed (a segment not matching `[A-Za-z0-9_]`, or bad separators) — by-path endpoints only.
`500`	Connector resolution failure or any unexpected exception.

Examples

# 1. Find an asset by name
curl -sG "https://portal.captureplatform.com/v2/uns/data/search" \
  -H "AuthVersion: V0.0.1" \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "name=Line 1" \
  --data-urlencode "type=line"

# 2. Browse children of that asset
curl -s "https://portal.captureplatform.com/v2/uns/assets/8b2e.../children?pageSize=50&currentPage=1" \
  -H "AuthVersion: V0.0.1" \
  -H "Authorization: Bearer <token>"

# 3. Snapshot the latest value of every variable under the asset
curl -s "https://portal.captureplatform.com/v2/uns/data/assets/8b2e.../latest" \
  -H "AuthVersion: V0.0.1" \
  -H "Authorization: Bearer <token>"

# 4. Raw history of one variable
curl -sG "https://portal.captureplatform.com/v2/uns/data/variables/c91a..." \
  -H "AuthVersion: V0.0.1" \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "from=2026-06-29T00:00:00Z" \
  --data-urlencode "to=2026-06-29T23:59:59Z" \
  --data-urlencode "limit=10000"

# 5. Aggregated (hourly) history of one variable
curl -sG "https://portal.captureplatform.com/v2/uns/data/variables/c91a.../aggregate" \
  -H "AuthVersion: V0.0.1" \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "from=2026-06-01T00:00:00Z" \
  --data-urlencode "to=2026-06-29T00:00:00Z" \
  --data-urlencode "interval=1h"

Headers​

How addressing works​

Endpoints at a glance​

Browsing the tree​

Pagination​

List Namespaces​

List Child Assets / Child Variables​

Get a Single Asset​

Get a Single Variable​

Search / List Variables​

Search Identifiers (assets & variables)​

Export a Subtree​

Nested Tree Under an Asset​

Reading values​

Latest Value Under an Asset​

Raw History of One Variable​

Raw History Under an Asset​

Aggregated History of One Variable​

Querying by UNS path​

The path parameter​

By-path equivalents​

Variable Schema (path only)​

Measurements Under an Asset (path only)​

Pagination guidance for history​

Error Responses​

Examples​

Headers

How addressing works

Endpoints at a glance

Browsing the tree

Pagination

List Namespaces

List Child Assets / Child Variables

Get a Single Asset

Get a Single Variable

Search / List Variables

Search Identifiers (assets & variables)

Export a Subtree

Nested Tree Under an Asset

Reading values

Latest Value Under an Asset

Raw History of One Variable

Raw History Under an Asset

Aggregated History of One Variable

Querying by UNS path

The `path` parameter

By-path equivalents

Variable Schema (path only)

Measurements Under an Asset (path only)

Pagination guidance for history

Error Responses

Examples