GraphQL reference: notification-management

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/notification-management/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/notification-management.graphql
Described	154 of 154 elements

Queries

notificationChannelTypes · notificationChannels · notificationChannelsById · notificationChannelsByToken · notificationPolicies · notificationPoliciesById · notificationPoliciesByToken · notificationStates · notificationStatesByAlarmToken

notificationChannelTypes

Lists the channel types the service can deliver through. The list is fixed: smtp and webhook. Requires no specific authority.

Returns [NotificationChannelType!]!

notificationChannels

Searches the tenant's channels, newest created first. Returns an empty page when nothing matches. Requires notification:read.

Returns NotificationChannelSearchResults!

Argument	Type	Description
criteria	NotificationChannelSearchCriteria!	Filters and paging.

notificationChannelsById

Returns the channels with the given server-assigned ids. Ids that match nothing are left out; an id that is not a non-negative integer fails the request. Requires notification:read.

Returns [NotificationChannel!]!

Argument	Type	Description
ids	[String!]!	Channel ids, as returned in id.

notificationChannelsByToken

Returns the channels with the given tokens. Tokens that match nothing are left out. Requires notification:read.

Returns [NotificationChannel!]!

Argument	Type	Description
tokens	[String!]!	Channel tokens.

notificationPolicies

Searches the tenant's policies, newest created first, each with its rules. Returns an empty page when nothing matches. Requires notification:read.

Returns NotificationPolicySearchResults!

Argument	Type	Description
criteria	NotificationPolicySearchCriteria!	Filters and paging.

notificationPoliciesById

Returns the policies, with their rules, that have the given server-assigned ids. Ids that match nothing are left out; an id that is not a non-negative integer fails the request. Requires notification:read.

Returns [NotificationPolicy!]!

Argument	Type	Description
ids	[String!]!	Policy ids, as returned in id.

notificationPoliciesByToken

Returns the policies, with their rules, that have the given tokens. Tokens that match nothing are left out. Requires notification:read.

Returns [NotificationPolicy!]!

Argument	Type	Description
tokens	[String!]!	Policy tokens.

notificationStates

Searches the notification records, newest created first. Returns an empty page when nothing matches. Requires notification:read.

Returns NotificationStateSearchResults!

Argument	Type	Description
criteria	NotificationStateSearchCriteria!	Filters and paging.

notificationStatesByAlarmToken

Returns the notification records for the given alarm tokens. An alarm with no record (never notified, acknowledged or cleared, or whose record has been removed) is left out. Requires notification:read.

Returns [NotificationState!]!

Argument	Type	Description
alarmTokens	[String!]!	Tokens of the alarms.

Mutations

createNotificationChannel · createNotificationPolicy · deleteNotificationChannel · deleteNotificationPolicy · renameNotificationChannel · updateNotificationChannel · updateNotificationPolicy

createNotificationChannel

Creates a delivery channel. Rejects an unknown channel type, a config or metadata that is not a JSON object, a webhook config that is invalid or whose auth does not match whether a secret was supplied, and a token already in use. Requires notification:write.

Returns NotificationChannel!

Argument	Type	Description
request	NotificationChannelCreateRequest!	The new channel's fields.

createNotificationPolicy

Creates a routing policy together with its rules, all or nothing. Rejects a non-blank deviceTypeToken, a rule whose severity is not valid or whose channelToken matches no channel, and a token already in use. Requires notification:write.

Returns NotificationPolicy!

Argument	Type	Description
request	NotificationPolicyCreateRequest!	The new policy's fields and rules.

deleteNotificationChannel

Permanently deletes a channel and its stored secret. Returns true if a channel was deleted and false if none has the token. Refused, with extensions.code REFERENCE_VIOLATION, while any policy rule still uses the channel. Requires notification:write.

Returns Boolean!

Argument	Type	Description
token	String!	Token of the channel to delete.

deleteNotificationPolicy

Permanently deletes a policy and its rules. Returns true if a policy was deleted and false if none has the token. Requires notification:write.

Returns Boolean!

Argument	Type	Description
token	String!	Token of the policy to delete.

renameNotificationChannel

Changes a channel's token and nothing else. Its secret and the policy rules that use it are unaffected. Renaming to the token it already has succeeds without change. Fails if the new token is blank or is already used by another channel (extensions.code CONFLICT), or if no channel has the old token. Requires notification:write.

Returns NotificationChannel!

Argument	Type	Description
newToken	String!	The new token, which must be unused in the tenant.
token	String!	Current token of the channel.

updateNotificationChannel

Partially updates a channel. The whole update is rejected, with nothing written, if any part of it is invalid. Fails if no channel has the token. Last write wins; there is no concurrent-edit check. Requires notification:write.

Returns NotificationChannel!

Argument	Type	Description
request	NotificationChannelUpdateRequest!	The fields to change.
token	String!	Current token of the channel to update.

updateNotificationPolicy

Partially updates a policy. Omitted fields are left alone; a rules list replaces the whole rule set. The whole update is rejected, with nothing written, if any part of it is invalid. Fails if no policy has the token. Requires notification:write.

Returns NotificationPolicy!

Argument	Type	Description
expectedUpdatedAt	String	The updatedAt value you last read, as an RFC 3339 timestamp. If the policy has changed since, nothing is written and the call fails with "notification policy was modified by another writer; reload and try again" (no error code). Omit it to overwrite unconditionally.
request	NotificationPolicyUpdateRequest!	The fields to change.
token	String!	Token of the policy to update.

Objects

NotificationChannel · NotificationChannelSearchResults · NotificationChannelType · NotificationPolicy · NotificationPolicySearchResults · NotificationRule · NotificationState · NotificationStateSearchResults · SearchResultsPagination

NotificationChannel

object

A delivery channel: a configured email (SMTP) server or webhook endpoint that notifications are sent through. Routing policies refer to channels by token.

Field	Type	Description
channelType	String!	The channel type: smtp or webhook, as listed by notificationChannelTypes.
config	String	The channel's non-secret connection settings as a JSON object serialized to a string, or null if none are set. The shape depends on channelType; see NotificationChannelCreateRequest.config.
createdAt	String	When the channel was created, as an RFC 3339 timestamp.
deletedAt	String	Always null: deleting a channel removes it permanently rather than marking it deleted.
description	String	Free-text description of what the channel is for.
enabled	Boolean!	Whether the channel is in use. Notifications are not sent through a disabled channel.
hasSecret	Boolean!	True when a delivery secret is stored for the channel. The secret itself is never returned.
id	ID!	Server-assigned identifier. Address a channel by its token, not by this.
metadata	String	Free-form caller-defined metadata as a JSON object serialized to a string, or null if none is set.
name	String	Human-readable name shown in channel lists.
token	String!	Unique, caller-chosen identifier of the channel within the tenant. Letters, digits, hyphens and underscores, starting with a letter or digit, at most 128 characters.
updatedAt	String	When the channel was last written, as an RFC 3339 timestamp.

NotificationChannelSearchResults

object

One page of delivery channels and where it sits in the full result set.

Field	Type	Description
pagination	SearchResultsPagination!	Position of this page within the full result set.
results	[NotificationChannel!]!	The channels on this page, newest created first (ties broken by token).

NotificationChannelType

object

A kind of delivery channel the service can send notifications through. You pick a type when you create a channel.

Field	Type	Description
available	Boolean!	True when this build can actually deliver through the type. Both listed types are available.
description	String!	One-sentence explanation of what delivering through this type does.
id	String!	The identifier to pass as channelType when creating a channel: smtp or webhook.
label	String!	Short human-readable name for the type, for pickers.

NotificationPolicy

object

A routing policy: which raised alarms are sent to whom, through which channels, and whether an alarm that nobody acknowledges is re-sent. Policies apply to every device in the tenant.

Field	Type	Description
createdAt	String	When the policy was created, as an RFC 3339 timestamp.
deletedAt	String	Always null: deleting a policy removes it permanently rather than marking it deleted.
description	String	Free-text description of what the policy is for.
deviceTypeToken	String	Always null: policies cannot yet be limited to a device type, and a request that tries is refused.
enabled	Boolean!	Whether the policy is active. A disabled policy sends nothing.
escalateAfterSeconds	Int	Re-notify an alarm still neither acknowledged nor cleared this many seconds after its last notification. Null or 0 disables escalation for the policy. When several escalating policies match one alarm they share a single clock, driven by the shortest window.
id	ID!	Server-assigned identifier. Address a policy by its token, not by this.
maxEscalations	Int	Maximum number of re-notifications per alarm. Null or 0 uses the service-wide default (5 unless the operator changed it).
metadata	String	Free-form caller-defined metadata as a JSON object serialized to a string, or null if none is set.
name	String	Human-readable name shown in policy lists.
rules	[NotificationRule!]!	The policy's routing rules.
throttleSeconds	Int	Minimum number of seconds between notifications about the same alarm; a notification inside the window is suppressed, except when the alarm's severity has escalated. Null means no throttle.
token	String!	Unique, caller-chosen identifier of the policy within the tenant. Letters, digits, hyphens and underscores, starting with a letter or digit, at most 128 characters.
updatedAt	String	When the policy was last written, as an RFC 3339 timestamp. Pass it back as expectedUpdatedAt to make an update conditional on nobody else having changed the policy since you read it. Any update, including one that only replaces rules, moves it.

NotificationPolicySearchResults

object

One page of routing policies and where it sits in the full result set.

Field	Type	Description
pagination	SearchResultsPagination!	Position of this page within the full result set.
results	[NotificationPolicy!]!	The policies on this page, newest created first (ties broken by token), each with its rules.

NotificationRule

object

One routing rule inside a policy: alarms of a matching severity are sent through a channel to a list of recipients.

Field	Type	Description
channel	NotificationChannel	The channel the rule sends through; null if the channel no longer exists.
id	ID!	Server-assigned identifier. A policy update that supplies rules replaces them all, so rule ids change.
recipients	String	The recipients as a JSON array of strings serialized to a string, or null if none. For an smtp channel they are email addresses; a webhook rule needs none because the channel's endpoint is the destination.
severity	String!	The alarm severity this rule matches: CRITICAL, MAJOR, MINOR, WARNING, INDETERMINATE, or * for any severity.

NotificationState

object

What the service has done about one raised alarm: when it was notified, how many times, and how far escalation has gone. There is one record per alarm. It records notification activity, not the alarm itself; read the alarm from the alarms API.

Field	Type	Description
acknowledgedAt	String	When the alarm was acknowledged, as an RFC 3339 timestamp; null if it has not been. Escalation stops once it is set, and the record is removed after a retention period.
alarmKey	String!	The alarm's logical key, which identifies a kind of alarm on its originator.
alarmToken	String!	Token of the alarm this record is about.
clearedAt	String	When the alarm was cleared, as an RFC 3339 timestamp; null if it has not been. Escalation stops once it is set, and the record is removed after a retention period.
escalationLevel	Int!	Number of escalation steps taken for the alarm so far; 0 if none. A step is counted when it starts, so it is counted even if its delivery then fails.
firstNotifiedAt	String	Time of the alarm transition whose notification was the first delivered, as an RFC 3339 timestamp; null if none has been.
id	ID!	Server-assigned identifier of this record.
lastEscalatedAt	String	When the alarm was last escalated, as an RFC 3339 timestamp; null if it never has been.
lastNotifiedAt	String	Time of the most recent notification: the alarm transition's time, or when an escalation step started. RFC 3339; null if none.
notifyCount	Int!	Number of notifications recorded about the alarm, escalations included. An escalation step is counted when it starts, even if its delivery then fails.
severity	String!	The alarm's most recent severity known to this service, including a de-escalation, which is recorded without a notification.

NotificationStateSearchResults

object

One page of notification state records and where it sits in the full result set.

Field	Type	Description
pagination	SearchResultsPagination!	Position of this page within the full result set.
results	[NotificationState!]!	The records on this page, newest created first.

SearchResultsPagination

object

Where a page of search results sits in the full result set. Positions are 1-based and inclusive.

Field	Type	Description
pageEnd	Int	Position of the last result on this page within the full result set (1-based, inclusive).
pageStart	Int	Position of the first result on this page within the full result set (1-based).
totalRecords	Int	Number of records matching the criteria across all pages.

Input types

NotificationChannelCreateRequest · NotificationChannelSearchCriteria · NotificationChannelUpdateRequest · NotificationPolicyCreateRequest · NotificationPolicySearchCriteria · NotificationPolicyUpdateRequest · NotificationRuleCreateRequest · NotificationStateSearchCriteria

NotificationChannelCreateRequest

input

Fields for a new delivery channel. The type must be one listed by notificationChannelTypes and the config must be valid for it.

Input field	Type	Description
channelType	String!	The channel type: smtp or webhook, as listed by notificationChannelTypes.
config	String	The non-secret connection settings as a JSON object serialized to a string. For smtp: host, port, from, username (optional; requires a secret) and security (starttls, the default; tls; or none for cleartext). For webhook: url (http or https, required), method (POST only), headers (an object of extra request headers) and auth (required: none when the URL itself carries the credential, bearer to send the secret as a bearer token, or header to send it in the header named by authHeader, optionally prefixed with authScheme). A webhook with auth bearer or header must have a secret, and one with auth none must not. The platform restricts which destinations a channel may reach.
description	String	Free-text description of what the channel is for.
enabled	Boolean!	Whether the channel is active. Notifications are not sent through a disabled channel.
metadata	String	Free-form caller-defined metadata as a JSON object serialized to a string.
name	String	Human-readable name shown in channel lists.
secret	String	The delivery credential: the SMTP password or the webhook bearer or header value. Write-only; stored encrypted and never returned. Omit it, or send an empty string, for no secret.
token	String!	Unique identifier for the new channel within the tenant. Letters, digits, hyphens and underscores, starting with a letter or digit, at most 128 characters.

NotificationChannelSearchCriteria

input

Filters and paging for the notificationChannels query.

Input field	Type	Description
channelType	String	Return only channels of this type (smtp or webhook). Omit it to return every type.
enabled	Boolean	Return only enabled (true) or only disabled (false) channels. Omit it to return both.
pageNumber	Int!	Page to return, starting at 1. A value below 1 is treated as 1.
pageSize	Int!	Channels per page. A value below 1 is treated as 100; a value above 1000 is capped at 1000.

NotificationChannelUpdateRequest

input

A partial update to a delivery channel. Omit a field to leave the stored value alone, send a value to set it, or send an explicit null to clear it (except where noted). The channel is named by the mutation's token argument, so there is no token here; use renameNotificationChannel to change the token.

Input field	Type	Description
channelType	String	New channel type (smtp or webhook). Omit it to keep the stored type; an explicit null is refused.
config	String	New connection settings as a JSON object serialized to a string, in the format described on NotificationChannelCreateRequest.config, or null to clear them. For a webhook channel the result must still be valid, including its auth setting.
description	String	New description, or null to clear it.
enabled	Boolean	Whether the channel is active. Omit it to keep the stored value; an explicit null is refused.
metadata	String	New metadata as a JSON object serialized to a string, or null to clear it.
name	String	New name, or null to clear it.
secret	String	The write-only delivery credential. Omit it to keep the stored secret, send a value to replace it, or send null or an empty string to delete it. A webhook channel whose auth is bearer or header cannot be left without a secret, and one whose auth is none cannot have one.

NotificationPolicyCreateRequest

input

Fields for a new routing policy, including its complete rule set.

Input field	Type	Description
description	String	Free-text description of what the policy is for.
deviceTypeToken	String	Not supported yet: any non-blank value is rejected. Leave it unset to create a policy that applies to every device.
enabled	Boolean!	Whether the policy is active. A disabled policy sends nothing.
escalateAfterSeconds	Int	Seconds after an alarm's last notification before an unacknowledged, uncleared alarm is re-sent. Omit it or use 0 for no escalation.
maxEscalations	Int	Maximum number of re-notifications per alarm. Omit it to use the service-wide default.
metadata	String	Free-form caller-defined metadata as a JSON object serialized to a string.
name	String	Human-readable name shown in policy lists.
rules	[NotificationRuleCreateRequest!]!	The policy's complete rule set; pass an empty list for a policy with no rules yet.
throttleSeconds	Int	Minimum seconds between notifications about the same alarm. Omit it for no throttle.
token	String!	Unique identifier for the new policy within the tenant. Letters, digits, hyphens and underscores, starting with a letter or digit, at most 128 characters.

NotificationPolicySearchCriteria

input

Filters and paging for the notificationPolicies query.

Input field	Type	Description
deviceTypeToken	String	Return only policies scoped to this device type. Policies cannot yet be scoped, so any value matches nothing.
enabled	Boolean	Return only enabled (true) or only disabled (false) policies. Omit it to return both.
pageNumber	Int!	Page to return, starting at 1. A value below 1 is treated as 1.
pageSize	Int!	Policies per page. A value below 1 is treated as 100; a value above 1000 is capped at 1000.

NotificationPolicyUpdateRequest

input

A partial update to a routing policy. Omit a field to leave the stored value alone, send a value to set it, or send an explicit null to clear it (except where noted). The policy is named by the mutation's token argument, so there is no token here, and a policy's token cannot be changed.

Input field	Type	Description
description	String	New description, or null to clear it.
enabled	Boolean	Whether the policy is active. Omit it to keep the stored value; an explicit null is refused.
escalateAfterSeconds	Int	New escalation window in seconds, or null to disable escalation.
maxEscalations	Int	New maximum number of re-notifications per alarm, or null to use the service-wide default.
metadata	String	New metadata as a JSON object serialized to a string, or null to clear it.
name	String	New name, or null to clear it.
rules	[NotificationRuleCreateRequest!]	The policy's complete rule set. Omit it to leave the stored rules untouched. Send a list to replace all the rules with it, or send null or an empty list to remove all rules. Rules are replaced wholesale, never merged, and each rule gets a new id.
throttleSeconds	Int	New minimum seconds between notifications about the same alarm, or null to remove the throttle.

NotificationRuleCreateRequest

input

A routing rule supplied when creating or updating a policy. The channel is referred to by token; a token that matches no channel fails the whole write.

Input field	Type	Description
channelToken	String!	Token of the channel to send through.
recipients	String	The recipients as a JSON array of strings serialized to a string. For an smtp channel these are email addresses; a webhook rule needs none.
severity	String!	The alarm severity to match: CRITICAL, MAJOR, MINOR, WARNING or INDETERMINATE, or * for any. The match is exact and case-sensitive, so lowercase values are rejected.

NotificationStateSearchCriteria

input

Filters and paging for the notificationStates query.

Input field	Type	Description
alarmKey	String	Return only records for alarms with this logical key.
pageNumber	Int!	Page to return, starting at 1. A value below 1 is treated as 1.
pageSize	Int!	Records per page. A value below 1 is treated as 100; a value above 1000 is capped at 1000.
severity	String	Return only records with this severity, such as CRITICAL. Omit it to return all.