Device Fleet
Controllers, devices, edge apps, networks, metrics, telemetry and JMF device binding.
107 operations · complete schema 203 KB
magicQuery
Executes a Magic Query string and returns the predefined query's JSON result. On a bad noun or parameter, returns a structured error whose 'extensions' carry 'code', 'actionable_message', and 'suggestions' for self-correction.
getMagicQuerySchema
Returns the input JSON Schema and output introspection for a Magic Query noun, so consumers (especially LLMs) can learn its contract before calling magicQuery.
listMagicQueries
Lists every available Magic Query noun with a short description and its options — the discovery entry point.
getMagicQueryGraphQL
Resolves a Magic Query string to the real GraphQL operation and variables it runs, so consumers can graduate from the façade to raw GraphQL. Does not execute.
listDataChangeEventTopics
List all valid data change event topics, grouped by resource. Requires authentication.
generateDefaultDataQuery
Generate a default GraphQL data query for an event topic. Returns a query string with all scalar fields for the resource, or null if the topic has no matching query. The query uses $id as the variable for the resource ID.
ping
Health check endpoint
getNetwork
Fetch a single network by ID. Requires network:read permission.
listNetworks
List networks with pagination. Requires network:list permission.
getController
Fetch a single controller by ID. Requires controller:read permission.
controllerConnectionStatus
Check whether a controller has an active bridge connection. Requires controller:read permission.
controllerStatus
Latest discovery and health snapshot, with platform receipt time and freshness
listControllers
List controllers with pagination. Requires controller:list permission.
listControllerTokens
List controller tokens with pagination. Requires controller_token:list permission.
analyzeEdgeAppSource
Validate complete EdgeApp XML without saving; returns compiler catalog and original source ranges.
getEdgeApp
Fetch a edge app by ID. Requires edge_app:read permission.
listEdgeApps
List edge apps with pagination. Requires edge_app:list permission.
validateEdgeAppSource
Type-check edgeApp handler / library / onMessage Lua sources against the bridge's ambient API typedef without persisting anything. Safe to call from editors on every keystroke. Requires edge_app:read permission.
getEdgeAppSource
Read exact EdgeApp XML for authoring. Requires edge_app:write permission.
getEdgeAppInstallation
Fetch a edge app installation by ID. Requires edge_app_installation:read permission.
listEdgeAppInstallations
List edge app installations with pagination. Requires edge_app_installation:list permission.
getEdgeAppEvent
Fetch a edge app event by ID. Requires edge_app_event:read permission.
listEdgeAppEvents
List edge app events with pagination. Requires edge_app_event:list permission.
getControllerPolicy
Fetch a controller policy by its ID. Requires controller_policy:read permission.
getControllerPolicyByController
Fetch a controller's policy by the controller ID (the natural key). Returns null if no policy is configured (default-deny).
listControllerPolicies
List controller policies with pagination. Requires controller_policy:list permission.
getDevice
Fetch a single device by ID. Requires device:read permission.
listDevices
List devices with pagination. Requires device:list permission.
listDeviceTokens
List device tokens with pagination. Requires device_token:list permission.
getMetric
Fetch a single metric by ID. Requires metric:read permission.
listMetrics
List metrics with pagination. Requires metric:list permission.
getMetricPoints
Query time-series data points for a metric. Returns a flat array ordered by timestamp, with summary stats. Requires metric:read permission.
aggregateMetricPoints
Aggregate metric data points into time buckets with configurable statistics. Automatically routes to pre-computed continuous aggregates for HOUR/DAY/WEEK/MONTH intervals. Supports gap-filling (LOCF/interpolation), time-weighted averages, and counter delta/rate via Toolkit. For counter metrics, computes delta (last-first) per bucket instead of average. Requires metric:read permission.
metricHistogram
Compute a value distribution histogram for a metric over a time range. Range bounds are auto-detected if not specified. Requires metric:read permission.
metricPercentiles
Compute percentile values (e.g. p50, p95, p99) for a metric over a time range. Supports both exact (percentile_cont) and approximate (UddSketch via Toolkit) modes. Approximate mode is faster for large datasets. Useful for SLA analysis and outlier detection. Requires metric:read permission.
metricProjection
Compute a linear regression over historical data and project forward. Returns slope, R-squared, projected values with confidence intervals, and optionally the estimated time a target value will be reached. Requires metric:read permission.
compareMetrics
Compare multiple metrics side-by-side over the same time range and interval. Returns time-bucketed aggregates and summary statistics for each metric. Supports 2-10 metrics per request. Requires metric:read permission.
metricStateDuration
Analyze time spent in each discrete state for a status metric. Returns both a duration breakdown by state and a chronological timeline of state transitions (Gantt-chart-ready). Requires a metric with kind STATUS. Uses Toolkit state_agg(). Requires metric:read permission.
metricHeartbeat
Analyze uptime and downtime for a heartbeat-style metric. Detects gaps where no value was received within the expected interval. Returns total uptime/downtime, uptime percentage, and individual gap periods. Uses Toolkit heartbeat_agg(). Requires metric:read permission.
downsampleMetricPoints
Downsample metric data points for efficient visualization. Uses the Largest Triangle Three Buckets (LTTB) algorithm to preserve the visual shape of the time series while reducing point count. Optionally preserves gaps in data via gp_lttb(). Uses Toolkit lttb() / gp_lttb(). Requires metric:read permission.
metricCorrelation
Compute statistical correlation between two metrics over a time range. Returns Pearson correlation coefficient, slope, intercept, R-squared, and covariance. Metrics are joined by 1-second time buckets. Uses Toolkit stats_agg() 2D. Requires metric:read permission.
iacSchema
The infrastructure-only view of this schema, for declarative tooling. Contains only annotated resources and the types they reach.
iacValidate
Validate an infrastructure artifact. Pure and side-effect free; safe to alias many times in one document.
iacGuides
Every authoring guide, for a tool that syncs them to a folder. Intended for `schema pull` to call once and write to disk, not for an agent to call while authoring — a file can be grepped and re-read in part, where a response arrives whole.
helpChapters
List human-facing manual chapters from the running deployment.
helpChapter
Read a chapter of the current published manual edition.
searchHelp
Search human-facing manuals using shared semantic and text retrieval.
schemaAuthoringCatalog
Compiler-owned vocabulary for the standalone XML JSON Schema dialect, including native form annotations.
compileSchemaXML
Compile standalone XML schema syntax into JSON Schema without persisting it; host restrictions apply when embedded.
renderSchemaXML
Render JSON Schema as native XML without dropping unsupported keywords or changing a saved document.
iacSchemaDocument
Fetch the JSON Schema document a SCHEMA-kind validator references, for declarative tooling.
controllerJMFConfig
Read the bridge JMF endpoint configuration for this controller. This does not enable direct POST /api/v1/jmf; that is settings.jmf (Settings › JMF signals). Requires controller:read.
workCenterDeviceJMFDeviceID
Read the JMF DeviceID set on a work center ↔ device binding. Requires workCenter:read.
upsertNetwork
Create or update a network. Requires network:write permission.
createNetwork
Create a new network. Requires network:write permission.
updateNetwork
Update a network. Only provided fields are changed. Requires network:write permission.
deleteNetwork
Delete a network. Requires network:delete permission.
upsertController
Create or update a controller. Requires controller:write permission.
createController
Create a new controller. Requires controller:write permission.
updateController
Update a controller. Only provided fields are changed. Requires controller:write permission.
deleteController
Delete a controller. Requires controller:delete permission.
createControllerToken
Create a new controller token. Returns the signed token value. Requires controller_token:write permission.
revokeControllerToken
Revoke a controller token. Requires controller_token:revoke permission.
saveEdgeAppSource
Create or update EdgeApp XML and return the authoring view
publishEdgeAppSource
Publish only the reviewed EdgeApp XML; repeated immutable source is a no-op
upsertEdgeApp
Create or update a DRAFT edge app row. With `input.id`: edits the existing draft (rejects PUBLISHED/DEPRECATED rows — those are frozen). Without `input.id`: creates a new draft for the handle (rejects if a draft already exists). Drafts aren't pushed to controllers; use publishEdgeAppDraft to ship. Requires edge_app:write permission.
upsertEdgeAppSource
Compile, validate, and retain an EdgeApp XML document as a DRAFT. Omit id to create; provide a DRAFT id to replace its source.
createEdgeApp
Create a new DRAFT edge app row for `input.handle`. Rejects if a draft already exists for the handle (finish or delete it first). Drafts aren't pushed to controllers; use publishEdgeAppDraft to ship. Requires edge_app:write permission.
updateEdgeApp
Update an existing DRAFT edge app row. Rejects PUBLISHED/DEPRECATED rows (frozen) and attempts to change `handle` (immutable on an existing draft). Only provided fields are changed. Requires edge_app:write permission.
publishEdgeAppDraft
Freeze a DRAFT and flip it to PUBLISHED. Auto-deprecates the previously-PUBLISHED row for the same handle. Pushes config.update to every controller running an installation that pinned the newly-published row. Requires edge_app:write.
deprecateEdgeApp
Mark a PUBLISHED row as DEPRECATED. Used to retire an app without a replacement. Existing installations stay pinned and keep working until upgraded or uninstalled. Idempotent on already-DEPRECATED rows; rejects DRAFT rows (delete them instead). Requires edge_app:write permission.
deleteEdgeApp
Delete a edge app row. Cascades to all installations pinning this row and pushes config.update to each affected controller. Use deprecateEdgeApp instead to retire a PUBLISHED row without losing installation history.
invokeEdgeApp
Invoke a edgeApp's onMessage export by name on a specific controller (the edgeApp must be installed on it). Forwards to the bridge and returns the function's JSON return value. Requires edge_app:invoke permission.
exportEdgeApp
Export an edge app to YAML or JSON. Requires edge_app:read permission.
importEdgeApp
Import an edge app from YAML or JSON, landing it as a DRAFT (replaces an existing DRAFT for the handle, or allocates the next version). Requires edge_app:write permission.
upsertEdgeAppInstallation
Create or update a edgeApp installation. Validates `variables` against the edgeApp's configSchema (when set) and pushes config.update to the target controller. Requires edge_app_installation:write permission.
createEdgeAppInstallation
Create a edgeApp installation. Validates the edgeApp exists in this tenant and isn't DRAFT, that the controller exists, that an optional bot user exists, and `variables` against the edgeApp's configSchema (when set); pushes config.update to the target controller. Requires edge_app_installation:write permission.
updateEdgeAppInstallation
Update a edgeApp installation. Only provided fields are changed; `edgeAppId` is immutable (delete and recreate to change it). Re-validates the controller and bot user (if changed) and `variables` against the edgeApp's configSchema. Pushes config.update to the controller. Requires edge_app_installation:write permission.
upgradeEdgeAppInstallation
Repoint an installation at a different version of the same edgeApp. Validates the target row exists, belongs to this tenant, shares the installation's current handle, and isn't a DRAFT (only PUBLISHED or DEPRECATED versions can be pinned). Pushes config.update to the controller. The bridge reconciles by `installation.id`+`version`, so the new version triggers a restart with the new content. Requires edge_app_installation:write.
deleteEdgeAppInstallation
Delete a edgeApp installation. Triggers a config.update push to the controller.
upsertControllerPolicy
Create or update the policy for a controller. Idempotent on controllerId (one row per controller). Wholesale-replace on both allowlists. Triggers a config.update push to the controller. Requires controller_policy:write permission.
createControllerPolicy
Create a new controller policy. The referenced controller must exist in this tenant. Triggers a config.update push to the controller. Requires controller_policy:write permission.
updateControllerPolicy
Update a controller policy. Only provided fields are changed. The referenced controller must exist in this tenant. Triggers a config.update push to the controller. Requires controller_policy:write permission.
deleteControllerPolicy
Delete a controller's policy. The controller falls back to default-deny on the next config.update push. Requires controller_policy:delete permission.
upsertDevice
Create or update a device. Requires device:write permission.
createDevice
Create a new device. Requires device:write permission.
updateDevice
Update a device. Only provided fields are changed. Requires device:write permission.
deleteDevice
Delete a device. Requires device:delete permission.
createDeviceToken
Create a new device token. Returns the signed token value. Requires device_token:write permission.
revokeDeviceToken
Revoke a device token. Requires device_token:revoke permission.
upsertMetric
Create or update a metric. Requires metric:write permission.
createMetric
Create a new metric. Requires metric:write permission.
updateMetric
Update a metric. Only provided fields are changed. Requires metric:write permission.
recordMetricPoints
Record one or more data points for a metric. Requires metric:write permission.
deleteMetric
Delete a metric and all its data points. Requires metric:delete permission.
discoverDeviceJMFDevices
Discover the devices known to a JMF controller (KnownDevices). Requires device:execute permission.
interrogateDeviceJMFCapabilities
Interrogate the message services a JMF controller supports (KnownMessages). Requires device:execute permission.
setControllerJMFConfig
Configure the controller bridge JMF endpoint (generates basic-auth credentials when enabled). Direct /api/v1/jmf is configured separately with updateJmfSettings. Requires controller:write.
deleteControllerJMFConfig
Remove a controller's JMF configuration. Requires controller:write.
setWorkCenterDeviceJMFDeviceID
Set the canonical JMF DeviceID on a work center ↔ device binding for inbound correlation. The legacy WorkCenter.jmfDeviceId remains a fallback alias; it is not copied because a work center can have several controller-specific IDs. Requires workCenter:write.
updateJmfSettings
Turns the direct JMF endpoint on or off. The token is untouched.
setJmfToken
Sets or replaces the JMF access token with one you supply, e.g. the one your devices already send.
generateJmfToken
Sets or replaces the JMF access token with a new random one, returned once in the result.
removeJmfToken
Removes the JMF access token. While the endpoint is on, anything that can reach it can then post signals.
revealJmfToken
Shows the JMF access token so an operator can set up a device. Every reveal is recorded with who and when.
dataChangeEvents
Subscribe to real-time data change events. Requires read permission on each requested resource.
edgeAppLogStream
Stream new LOG-kind edgeApp events as they arrive for a single installation. Requires edge_app_event:read.