Values

Retrieves current values for points under a source.

GET /v1/values

curl -G https://api.novant.io/v1/values \
  -u ak_sample_123: \
  -d source_id=s.1 \
  --compressed

Parameters

source_id Required: Parent source ID for point list. One of source_id, source_ids, asset_id, or space_id is required. If multiple are specified, precedence is source_id, then source_ids, then asset_id, then space_id.
source_ids Required: Parent source IDs for point list. Limited to 10 sources. One of source_id, source_ids, asset_id, or space_id is required. If multiple are specified, precedence is source_id, then source_ids, then asset_id, then space_id.
asset_id Required: Parent asset ID for point list. One of source_id, source_ids, asset_id, or space_id is required. If multiple are specified, precedence is source_id, then source_ids, then asset_id, then space_id.
space_id Required: Parent space ID for point list. One of source_id, source_ids, asset_id, or space_id is required. If multiple are specified, precedence is source_id, then source_ids, then asset_id, then space_id.
point_ids: An allowlist to filter points by ID. Ids are formatted as a comma-separated list, i.e.: "s.1.1,s.1.2,s.1.5".
point_types: An allowlist to filter points by type. Types are formatted as a comma-separated list, i.e.: "discharge_air_temp_sensor,zone_air_temp_sensor".

Returns

Returns point values for the given source.

{
  "source_id": "s.1",
  "values": [
    {
      "id": "s.1.1",
      "val": 77.0,
      "status": "ok"
    },
    {
      "id": "s.1.2",
      "val": 3.0,
      "status": "ok"
    },
    {
      "id": "s.1.3",
      "val": 78.0,
      "status": "ok",
      "effective_level": 5,
      "levels": [
        {
          "level": 5,
          "val": 78.0,
          "who": "external"
        },
        {
          "level": 8,
          "val": 68.0,
          "who": "u.5",
          "expires": "2026-09-09T18:00:00Z"
        }
      ]
    },
    {
      "id": "s.1.4",
      "val": "na",
      "status": "fault",
      "err_code": "E12"
    },
    ...
  ]
}

Value Fields

Field	Description
`id`	Point ID.
`val`	Current value, or `"na"` when unavailable.
`status`	`ok`, `fault`, or `unknown`.
`err_code`	Error code, present only when `status` is `fault`.
`effective_level`	Priority level currently driving the point.
`levels`	The point’s priority array. Omitted when empty.

See Error Codes for details on each err_code.

Priority Levels

Writable points carry a 16-slot priority array, where the lowest-numbered occupied slot wins. levels lists only the occupied slots, ordered ascending, and effective_level is the level of the first entry.

Each entry reports which actor holds the slot:

Field	Description
`level`	Priority level, `1` through `16`.
`val`	Value held at this level.
`who`	Who holds the slot - see below.
`expires`	When the hold is released automatically, when set (in ISO 8601 format).

who is "external" for slots commanded by a system other than Novant, read back from the device. Otherwise it is the scoped id of the Novant actor that issued the write - a user (u.5), a schedule (sch.1), a scene (sn.2), or "api" for a write issued through this API.

In the example above the point reads 78.0 because an external system holds level 5, even though Novant is commanding 68.0 at level 8. Expired holds are omitted, and read-only points have no levels array at all.