GraphQL reference: event-processing

Generated from the schema this service serves, so it cannot fall behind it. The same schema is published as a file for tools and agents.

Endpoint	https://<your-host>/api/event-processing/graphql
Auth plane	tenant — The ordinary application plane. Obtain a tenant access token by calling login then selectTenant on user-management, and authorize each call with the capability it names (for example device:write).
Authorize with	tenant access token
Schema file	/schema/event-processing.graphql
Described	120 of 120 elements

Queries

compileCanvas · eventProcessingInfo · previewRule · ruleHealth · validateDetectionRules

compileCanvas

Compiles a visual automation canvas into its detection-rule definition, without saving anything. A canvas must author exactly one rule; a graph with zero or several condition nodes is rejected with a diagnostic. The same compiler and cost check as the form builder are used, so the definition is equivalent to the form-authored rule. Problems are reported as diagnostics with ok=false, not as GraphQL errors. Requires device:read.

Returns CanvasCompileResult!

Argument	Type	Description
graph	String!	The canvas definition, as the JSON document the console editor emits, serialized to a string.
profileToken	String!	Token of the device profile the rule belongs to; every source node in the graph must be scoped to this profile.

eventProcessingInfo

Returns the identity of the event-processing service. Useful as a liveness check; it reads no tenant data.

Returns EventProcessingInfo!

previewRule

Runs a draft detection rule against replayed history and reports the raise and resolve edges it would have produced: what the rule would have done. The draft is named by exactly one of graph and ruleDefinition. Nothing is saved or published and live detection is not affected.

Problems with the request or the draft (bad window, compile failure, both or neither draft given) come back as ok=false with diagnostics. An unpublished profile, history that has aged out, a scan limit or too many concurrent previews return ok=true with the reason in degraded. Requires device:read, and also location:read when the draft tests geofence containment, because the result reveals when a device was inside a region.

Returns PreviewResult!

Argument	Type	Description
input	PreviewRuleInput!	The draft rule, the profile and the time window to replay.

ruleHealth

Returns the health of each live detection rule of a profile's active published version: status, last fire and lifetime fire count. Returns an empty list for a profile with no published version. Read-only. Requires device:read.

Returns [RuleHealth!]!

Argument	Type	Description
profileToken	String!	Token of the device profile.

validateDetectionRules

Checks a batch of detection-rule definitions by decoding, compiling and cost-checking each one, without saving anything. Returns valid=false with one error per rejected rule; rules that compile may still produce advisory warnings. Pure validation: no state is read or written, so it is safe to call repeatedly. Requires device:read.

Returns DetectionRuleValidationResult!

Argument	Type	Description
rules	[DetectionRuleInput!]!	The rules to check, in order; the index in each error and warning refers to this list.

Mutations

draftDetectionRuleFromText

draftDetectionRuleFromText

Drafts a detection rule from a plain-language description using the tenant's configured AI provider. The candidate is run through the same compiler as every other authoring path and, if it does not compile, repaired up to three inference rounds in total. Nothing is saved: you review the returned draft and save it through the normal rule-creation path.

When inference is not enabled on the deployment, no provider is active, the tenant has not opted in to external AI, the inference service could not be reached, or the tenant is over its drafting rate limit before a first candidate is produced, the result has unavailable=true rather than a GraphQL error. Each call spends inference budget, so it is a mutation and should not be retried blindly. Requires device:write.

Returns DraftRuleResult!

Argument	Type	Description
input	DraftRuleFromTextInput!	The description to draft from, the target profile, and optional metric hints.

Subscriptions

detectionStream

detectionStream

Streams a device profile's detections as they fire: every raised or resolved edge of a rule belonging to the profile, including rules with no alarm action. Live from the moment of subscription, with no backfill; use ruleHealth or previewRule for history. Scoped to the caller's tenant. An empty profileToken is an error. Requires device:read.

Returns DetectionEvent!

Argument	Type	Description
profileToken	String!	Token of the device profile whose detections to stream.

Objects

CanvasCompileResult · CanvasDiagnostic · DetectionEvent · DetectionRuleValidationError · DetectionRuleValidationResult · DetectionRuleValidationWarning · DraftDiagnostic · DraftRuleResult · EventProcessingInfo · NodeTraceStep · PreviewFiring · PreviewResult · PreviewStats · RuleHealth

CanvasCompileResult

object

The outcome of compiling one automation canvas.

Field	Type	Description
definition	String	The compiled rule definition, as a JSON document serialized to a string. Null when ok is false.
diagnostics	[CanvasDiagnostic!]!	One entry per problem or advisory finding. Empty when there is nothing to report.
estimatedCost	Int	The compiled predicate's worst-case evaluation cost, in the engine's cost units. Null when ok is false.
ok	Boolean!	True only if the graph compiled to exactly one rule and passed the cost check. Save or publish only when true.

CanvasDiagnostic

object

A compile diagnostic about a canvas or a draft rule, anchored to a node where it can be.

Field	Type	Description
code	String	Stable code identifying a rule-compiler warning (for example negatedAttributeGuard); null for a diagnostic that has none.
message	String!	English text for the diagnostic, which is also the fallback when the code is not localized.
nodeId	String	Id of the offending canvas node; null for a problem with the graph as a whole (for example a cycle or a dangling edge) or when the draft was not a canvas.
params	[String!]!	The values the code's text interpolates, in a fixed order per code. Empty when code is null.
severity	String!	Either "error", which rejects the graph, or "warning", which is advisory and the graph still compiled.

DetectionEvent

object

One detection on the live feed.

Field	Type	Description
edge	String!	The transition: "raised" or "resolved".
kind	String!	The rule's type, for example threshold, deltaRate, repeating, duration, absence, aggregate, correlation or connectivity.
occurredTime	String!	Event time the detection is stamped at, as an RFC 3339 timestamp.
ruleId	String!	Runtime id of the rule that fired.
ruleToken	String!	Token of the rule that fired, which links the detection to its rule in the profile.
series	String!	What the detection is keyed on: a device token, or the anchor's token for a correlation rule.
severity	String	The rule's severity: critical, major, minor, warning or indeterminate; null when the rule declares none.
value	Float	The value that triggered a raised edge; null on a resolved edge and for rules with no triggering scalar.

DetectionRuleValidationError

object

A rule that was rejected.

Field	Type	Description
index	Int!	Zero-based position of the rejected rule in the submitted list.
message	String!	Why the rule was rejected, in English, suitable for showing to the rule's author.
token	String!	The rejected rule's token, as submitted.

DetectionRuleValidationResult

object

The outcome of validating a batch of detection rules.

Field	Type	Description
errors	[DetectionRuleValidationError!]!	One entry per rejected rule. Empty when valid.
valid	Boolean!	True only if every submitted rule decoded, compiled and passed the cost check; equivalent to errors being empty.
warnings	[DetectionRuleValidationWarning!]!	Advisory findings on rules that did compile. A warning never makes the batch invalid: the rule is accepted and evaluates as written.

DetectionRuleValidationWarning

object

An advisory finding on a rule that compiled.

Field	Type	Description
code	String!	Stable code identifying the finding (for example negatedAttributeGuard). Localize text from the code and params.
index	Int!	Zero-based position of the rule in the submitted list.
message	String!	English fallback text for the finding.
params	[String!]!	The values the code's text interpolates, in a fixed order per code.
token	String!	The rule's token, as submitted.

DraftDiagnostic

object

One reason a drafted rule was rejected, or one advisory finding on a draft that compiled.

Field	Type	Description
code	String	Stable code of an advisory finding, as in CanvasDiagnostic.code; null on a rejection reason.
field	String	The rule field the finding is about (for example "when" or "threshold"); null when it is not tied to a field.
message	String!	English text suitable for showing to the author.
params	[String!]!	The values the code's text interpolates. Empty when code is null.

DraftRuleResult

object

The outcome of a natural-language drafting request.

Field	Type	Description
attempts	Int!	Number of inference rounds that produced a candidate (at most 3); 0 when unavailable.
definition	String	The compiled rule definition, as a JSON document serialized to a string, without a token (assigned when saved). Null unless ok.
diagnostics	[DraftDiagnostic!]!	The compiler's reasons for rejecting the last candidate. Empty when ok.
estimatedCost	Int	The compiled predicate's worst-case evaluation cost, in the engine's cost units. Null unless ok.
model	String	The model that produced the candidate; null if no candidate was produced.
ok	Boolean!	True when a candidate compiled.
provider	String	The AI provider that produced the candidate; null if no candidate was produced.
rawCandidate	String	The model's last rejected output, so the author can see what it tried. Set only when ok is false and a candidate was produced.
unavailable	Boolean!	True when inference could not run: not enabled on the deployment, no active provider, the tenant has not opted in to external AI, the inference service could not be reached, or the tenant is over its drafting rate limit before a first candidate was produced.
unavailableReason	String	A fixed, non-technical explanation when unavailable is true; null otherwise.
warnings	[DraftDiagnostic!]!	Advisory findings on a draft that compiled. The rule is accepted and behaves as written, but the author should read them before saving. Empty unless ok.

EventProcessingInfo

object

Identity of the event-processing service.

Field	Type	Description
functionalArea	String!	The functional area this service serves; always "event-processing".

NodeTraceStep

object

What one canvas node did for a single firing.

Field	Type	Description
detail	String	Short explanation, for example why a branch blocked or an action was inert; null when the disposition is self-explanatory.
disposition	String!	What the node did: "delivered" (source); "raised" or "resolved" (condition); "passed", "blocked" or "skipped" (branch); "raised", "sent", "cleared", "inert" or "skipped" (action).
kind	String!	The node's category: "source", "condition", "branch" or "action".
nodeId	String!	Id of the canvas node, matching a node in the request's graph.

PreviewFiring

object

One edge the draft would have produced.

Field	Type	Description
occurredAt	String!	Event time of the edge, as an RFC 3339 timestamp.
series	String!	What the edge is for: a device token, or the anchor's token for a correlation rule.
signal	String!	"raised" for a rising edge or "resolved" for a falling edge.
trace	[NodeTraceStep!]!	What each canvas node did for this firing, from source through condition and branches to actions. Empty unless the request set trace and the draft is a canvas graph. A branch that feeds two actions appears once per action path.

PreviewResult

object

The outcome of a replay preview.

Field	Type	Description
degraded	String	Why the result is partial: for example history before the window is no longer retained, a read or scan limit was reached, the window was shortened, the profile is unpublished, the geofence archive is unreachable, or too many previews are already running for the tenant. Null for a complete result.
diagnostics	[CanvasDiagnostic!]!	When ok is false, the reasons the request or draft was rejected; when ok is true, advisory warnings about the compiled draft.
firings	[PreviewFiring!]!	The edges the draft would have produced, ordered by time, then series, with raised before resolved at the same instant.
ok	Boolean!	True when the draft compiled and the replay ran, even if it found no firings. False when the request or draft was rejected; the reasons are in diagnostics.
stats	PreviewStats!	Coverage counters for the run.

PreviewStats

object

Coverage counters for a preview run.

Field	Type	Description
evalErrors	Int!	How many in-scope samples the rule could not evaluate because of a predicate error. A nonzero value adds a note to degraded, so a rule that errors is not mistaken for a quiet one.
eventsScanned	Int!	How many in-scope events were processed.
firingCount	Int!	How many edges were produced.
wallMs	Int!	Server-side wall-clock time the replay took, in milliseconds.

RuleHealth

object

Health of one live detection rule.

Field	Type	Description
fireCount	Int!	How many times the rule has fired over its lifetime; 0 if never. Approximate, since a replay can count a firing again, and capped at 2147483647.
lastFiredAt	String	When the rule last fired, as an RFC 3339 timestamp of the event time; null if it has never fired.
lastSignal	String	The edge of the most recent fire, "raised" or "resolved"; null if the rule has never fired.
message	String	Why the rule does not compile when status is COMPILE_ERROR; null otherwise.
name	String!	The rule's display name from its definition, or its token when it has none.
ruleId	String!	The rule's runtime id, composed as {tenant}/{profileVersionToken}/{ruleToken}.
ruleToken	String!	The rule's token, its stable id within the profile.
status	RuleStatus!	Whether the rule is running or no longer compiles.

Input types

DetectionRuleInput · DraftRuleFromTextInput · MetricHintInput · PreviewRuleInput

DetectionRuleInput

input

One detection rule submitted for validation.

Input field	Type	Description
definition	String!	The rule definition, as a JSON document serialized to a string.
groupScoped	Boolean = false	Whether the rule is scoped to a device group. Some rule kinds (absence and correlation) cannot be group-scoped and are rejected if this is true. Defaults to false.
token	String!	The rule's token, used to name the rule in errors and warnings.

DraftRuleFromTextInput

input

Input to draftDetectionRuleFromText.

Input field	Type	Description
metrics	[MetricHintInput!]	Optional metric vocabulary of the target profile, so the model refers to real metric keys. Omit it and the model works from the description alone.
profileToken	String!	Token of the target device profile.
text	String!	The author's plain-language description of the rule they want.

MetricHintInput

input

One metric of the target profile's vocabulary, offered to the model as context. Only key is required.

Input field	Type	Description
dataType	String	The metric's data type, as a hint.
description	String	What the metric measures, as a hint.
key	String!	The metric's key.
unit	String	The metric's unit, as a hint.

PreviewRuleInput

input

Input to previewRule. Exactly one of graph and ruleDefinition names the draft.

Input field	Type	Description
end	String!	End of the replay window by event occurred time, as an RFC 3339 timestamp. Must be after start. A window longer than 24 hours is shortened to the 24 hours ending at end, and the result says so in degraded.
graph	String	A canvas definition, as the JSON document the console editor emits, serialized to a string.
profileToken	String!	Token of the device profile whose published history the draft is replayed against.
ruleDefinition	String	A rule definition, as a JSON document serialized to a string (the form builder's output).
start	String!	Start of the replay window by event occurred time, as an RFC 3339 timestamp.
trace	Boolean	When true and the draft is a canvas graph, each firing carries a per-node trace of what every canvas node did for it. Off by default; ignored for a ruleDefinition draft.

Enums

RuleStatus

RuleStatus

enum

The status of a live detection rule.

Value	Description
ACTIVE	The rule compiles under the current limits and is running.
COMPILE_ERROR	The published rule no longer compiles under the current limits (for example after a maximum rule duration was lowered). It is surfaced so its author can re-author it. A rule that failed to compile at publish time never reaches this state, because publishing is refused.