Explorer

The Explorer API allows discovery of sources and point lists for devices behind an edge node. Use it to find available equipment to speed onboarding data into projects.

Discovery runs in two steps: a scan finds sources on the network, and a learn reads the point list from a source you found. Both run on the edge node and take minutes rather than seconds, so both are asynchronous - you queue the operation, then poll for its status.

The endpoints split along that line:

Discovering sources

Queue a scan and note the returned op_id:

curl https://api.novant.io/v1/explorer/scan \
  -X POST -u ak_sample_123: \
  -d op=bacnet-scan

{ "status": "ok", "op_id": "0a1b2c3d4e5f6a7b" }

Poll Ops until that id reaches a terminal state, waiting at least 30 seconds between requests:

curl https://api.novant.io/v1/explorer/ops \
  -u ak_sample_123:

{ "ops": [
    { "id": "0a1b2c3d4e5f6a7b", "op": "bacnet-scan",
       "state": "ok", "summary": "Found 12 sources",
     "finished": "2026-08-08T13:56:14.882Z" }
] }

A state of ok or error means the operation is done. Then read the results from Sources:

curl https://api.novant.io/v1/explorer/sources \
  -u ak_sample_123:

Each source carries a discovery id and a last_scan timestamp. Sources accumulate across scans, so compare last_scan to identify what the most recent scan found.

Reading points from a source

Pass a source’s discovery id to Learn:

curl https://api.novant.io/v1/explorer/learn \
  -X POST -u ak_sample_123: \
  -d source_id=c1578fe370e4

Poll Ops the same way. Learn operations include a source_id field, so you can tell which source each one is reading. Once it completes, the point list is available from Points:

curl -G https://api.novant.io/v1/explorer/points \
  -u ak_sample_123: \
  -d source_id=c1578fe370e4

The source’s point_count and last_learn fields are populated at the same time, so /v1/explorer/sources alone is enough to see which sources have been learned.

Practical notes

Poll no faster than every 30 seconds. A single Ops request returns every outstanding operation, so queueing several learns and polling once is both faster and cheaper than tracking each one separately. Every request counts against your monthly API usage - see Rate Limits.

Queue depth is limited. If the project already has the maximum number of operations outstanding, scan and learn return 429. Wait for queued work to finish and retry.

Discovery ids are not project ids. Explorer sources use an opaque discovery id (i.e.: "c1578fe370e4"). A source only receives an s.<n> id once it has been bound into the project, after which it appears in the Sources API.

Scans do not bind anything. Discovery is read-only with respect to your project - it tells you what is reachable from the edge node. Binding sources into the project is a separate step.

Operations require a read-write API key. Scan and learn return 403 for read-only keys. Reading sources, points, and ops works with any key.