Skip to main content
On this page

GraphQL API

The TowerOps GraphQL API provides a flexible, strongly-typed interface for querying and managing your network infrastructure. Request exactly the data you need in a single request, no over-fetching, no under-fetching.

The GraphQL API uses the same authentication as the REST API and provides equivalent functionality with the added benefit of nested queries and precise field selection.

Everything below is generated from the Absinthe schema this server is actually running, 33 queries, 49 mutations, 3 subscriptions and 69 types, restricted to the operations and types published for integration.

Authentication

Authenticate using a Bearer token in the Authorization header. 

Authorization: Bearer YOUR_API_TOKEN

API tokens carry an explicit scope list; queries and subscriptions require the resource's read scope and mutations require its write scope (devices:read, devices:write, …). A request without the required scope returns a GraphQL error naming the missing scope. Tokens created before scopes existed keep full access. See the REST reference for the full scope table and the OAuth 2.0 client credentials flow for partner apps.

Scope Grants
sites:read View sites
sites:write Create, update and delete sites
devices:read View devices, metrics and interfaces
devices:write Create, update and delete devices
checks:read View service checks and their results
checks:write Create, update and delete service checks
alerts:read View alerts
alerts:write Acknowledge, resolve, snooze and escalate alerts
agents:read View monitoring agents
agents:write Create and delete monitoring agents
organization:read View organization details
organization:write Update organization settings
members:read View members and pending invitations
members:write Invite members, change roles and remove members
integrations:read View integrations
integrations:write Create, update, test and delete integrations
coverages:read View RF coverage predictions
coverages:write Create, recompute and delete coverage predictions
config:read View schedules, escalation policies and maintenance windows
config:write Manage schedules, escalation policies and maintenance windows
activity:read View the organization activity feed
discovery:read View discovered device candidates
discovery:write Add or ignore discovered device candidates
webhooks:manage Manage outbound webhook endpoints and deliveries
subscribers:read View customers, subscriber traces, and subscriber impact for alerts and open outages
rf:read View RF link health, wireless clients and RF planning resources
rf:write Create and update RF planning towers, radios and links
backups:read View configuration backups and their status
backups:write Request configuration backups
reports:read View reports and download their CSV
reports:write Run reports now
status_pages:read View the status page, its components and incidents
tokens:manage List, create and revoke the organization's API tokens
admin:manage superuser only Superuser administration (MIB files, GeoIP data)

Create a token in Account Settings → API Tokens

Endpoint

All GraphQL requests are sent as POST to a single endpoint: 

POST https://staging.towerops.net/api/graphql

Send a JSON body with a query field and optional variables: 

curl -X POST https://staging.towerops.net/api/graphql \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ devices(limit: 100) { id name ipAddress status } }"}'

Queries are limited to a depth of 10 and a complexity of 500, where a list field's complexity is multiplied by its limit (or a default page estimate when it takes none), a wide selection over a large limit can exceed the budget, so page big lists with a smaller limit. Batched requests (a JSON array body, or a _json/operations query parameter) may carry at most 10 operations. Introspection queries are rejected in production: use this page for the schema rather than __schema .

For codegen clients the schema is published as files instead of introspection: /api/graphql/schema.graphql serves the SDL, and /api/graphql/schema.json the introspection JSON, both public and rate-limited like openapi.json.

Queries

Read operations. An API token's organization is implied; a mobile session passes organizationId to choose one.

activity [ActivityItem]

The organization's recent activity feed, newest first. Requires the `activity:read` scope. `page`/`perPage` select one page of the merged feed (the same items `activityPage` reports with metadata); `limit` selects the legacy bounded list, and the two styles cannot be combined in one request.

Argument Type Default Description
limit Int - Maximum number of activity items to return. Defaults to 50 and is capped at 500. Cannot be combined with `page` or `perPage`.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.
page Int - 1-based page number; defaults to 1. Cannot be combined with `limit`.
perPage Int - Page size. Defaults to 20 and is capped at 100. Cannot be combined with `limit`.
type String - Only items of this activity type; an unrecognised type is a field error. Allowed values: config_change, alert_fired, alert_resolved, device_event, sync, device_added, discovery_candidate.

activityPage ActivityPage

One page of the activity feed with its metadata, the newest 500 items pageable. Requires the `activity:read` scope.

Argument Type Default Description
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.
page Int - 1-based page number; defaults to 1. A page past the end returns empty `entries`.
perPage Int - Page size. Defaults to 20 and is capped at 100.
type String - Only items of this activity type; an unrecognised type is a field error. Allowed values: config_change, alert_fired, alert_resolved, device_event, sync, device_added, discovery_candidate.

agent Agent

Fetches a single agent by ID. Requires the `agents:read` scope.

Argument Type Default Description
id ID! - ID of the agent.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

agents [Agent]

Lists the organization's monitoring agents. Requires the `agents:read` scope.

Argument Type Default Description
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

alert Alert

Fetches a single alert by ID. Covers alerts with no device, such as `agent_offline`, and does not distinguish an alert in another organization from one that does not exist. Requires the `alerts:read` scope.

Argument Type Default Description
id ID! - ID of the alert.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

alerts [Alert]

Lists alerts in the organization, optionally filtered by status, device or a `triggered_at` range. Requires the `alerts:read` scope. `page`/`perPage` select one page of the collection (the same rows `alertsPage` reports with metadata); `limit` selects the legacy bounded list, and the two styles cannot be combined in one request. `triggeredSince`/`triggeredUntil` replace the seven-day-or-unresolved default with an inclusive `triggered_at` range, a lower bound without an upper bound closes at the request's `as_of`, so rows and the page's totalCount share one instant. A write committed after `as_of` can carry an earlier `triggered_at`, so resume a few minutes before the prior `as_of`; the overlap is idempotent. DEPRECATED: use `alertsPage`. This field silently truncates the collection at 100 rows when no `limit` is passed (issue 2618).

Deprecated: Use alertsPage, this field truncates the collection at 100 rows when no limit is passed

Argument Type Default Description
deviceId ID - Only alerts raised for this device.
limit Int - Maximum number of alerts to return. Defaults to 100 and is capped at 500. Cannot be combined with `page` or `perPage`.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.
page Int - 1-based page number; defaults to 1. Cannot be combined with `limit`.
perPage Int - Page size. Defaults to 20 and is capped at 100. Cannot be combined with `limit`.
status String - Only alerts in this state (`active`, `acknowledged` or `resolved`).
triggeredSince String - Only alerts whose `triggered_at` is at or after this ISO 8601 instant are listed; replaces the seven-day-or-unresolved default.
triggeredUntil String - Only alerts whose `triggered_at` is at or before this ISO 8601 instant are listed.

alertsPage AlertPage

One page of the alert collection with its metadata. Requires the `alerts:read` scope.

Argument Type Default Description
deviceId ID - Only alerts raised for this device.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.
page Int - 1-based page number; defaults to 1. A page past the end returns empty `entries`.
perPage Int - Page size. Defaults to 20 and is capped at 100.
status String - Only alerts in this state (`active`, `acknowledged` or `resolved`).
triggeredSince String - Only alerts whose `triggered_at` is at or after this ISO 8601 instant are listed; replaces the seven-day-or-unresolved default.
triggeredUntil String - Only alerts whose `triggered_at` is at or before this ISO 8601 instant are listed.

check Check

Fetches a single service check by ID. Soft-deleted checks are not returned. Requires the `checks:read` scope.

Argument Type Default Description
id ID! - ID of the check.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

checkResults [CheckResultPoint]

Historical results for a monitoring check, such as ping or HTTP, newest first. Returns at least 1,000 rows, scaling to 120 points per hour of `timeRange` (43,200 rows maximum). Requires the `checks:read` scope.

Argument Type Default Description
checkId ID! - ID of the check.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.
timeRange String "1h" How far back to read, given in hours (`1h`, `24h`). Missing or invalid ranges use one hour. Clamped to 1-720 hours (30 days).

checks [Check]

Lists the organization's HTTP, TCP, DNS and ping service checks. Requires the `checks:read` scope.

Argument Type Default Description
checkType String - Only checks of this type (`http`, `tcp`, `dns` or `ping`).
deviceId ID - Only checks attached to this device.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

device Device

Fetches a single device by ID, with its site preloaded. Requires the `devices:read` scope.

Argument Type Default Description
id ID! - ID of the device.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

deviceInterfaces [Interface]

SNMP interfaces discovered on a device. Empty when the device has no SNMP data. Requires the `devices:read` scope.

Argument Type Default Description
deviceId ID! - ID of the device.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

deviceMetrics [MetricPoint]

Time-series metrics for a device, assembled from the results of the monitoring checks attached to it. Requires the `devices:read` scope. Series cover the requested window, downsampling when needed to return at most 1,000 points per check and 5,000 across the device.

Argument Type Default Description
deviceId ID! - ID of the device to read metrics for.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.
sensorType String - Only results from checks of this type.
timeRange String "24h" How far back to read, given in hours (`24h`, `72h`); anything unparseable falls back to 24 hours. Clamped to 1-720 hours (30 days).

deviceSensors [Sensor]

SNMP sensors discovered on a device. Empty when the device has no SNMP data. Requires the `devices:read` scope.

Argument Type Default Description
deviceId ID! - ID of the device.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

devices [Device]

Lists devices in the organization, optionally filtered by site, status or seven-day monitoring coverage. Requires the `devices:read` scope. `page`/`perPage` select one page of the collection (the same rows `devicesPage` reports with metadata); `limit` selects the legacy bounded list, and the two styles cannot be combined in one request. `updatedSince` narrows the collection to devices whose `updated_at` is at or after that instant, closed at the request's `as_of`, a lower bound without an upper bound, so the window applies to the rows and the page's totalCount alike. A write committed after `as_of` can carry an earlier `updated_at`, so resume a few minutes before the prior `as_of`; the overlap is idempotent. DEPRECATED: use `devicesPage`. This field silently truncates the collection at 100 rows when no `limit` is passed, so a search can miss devices that exist (issue 2618).

Deprecated: Use devicesPage, this field truncates the collection at 100 rows when no limit is passed

Argument Type Default Description
coverageBelow Int - Only active monitored devices below this seven-day coverage percentage.
limit Int - Maximum number of devices to return. Capped at 500; omitted, the first 100 are returned. Cannot be combined with `page` or `perPage`.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.
page Int - 1-based page number; defaults to 1. Cannot be combined with `limit`.
perPage Int - Page size. Defaults to 20 and is capped at 100. Cannot be combined with `limit`.
search String - Matches device name, IP address, MAC (any spelling) or serial, the same filter the fleet page and REST `?search=` apply.
siteId ID - Only devices at this site.
status String - Only devices in this status (`up`, `down` or `unknown`).
updatedSince String - Only devices whose `updated_at` is at or after this ISO 8601 instant are listed. The window closes at the request's `as_of`.

devicesPage DevicePage

One page of the device collection with its metadata. Requires the `devices:read` scope.

Argument Type Default Description
coverageBelow Int - Only active monitored devices below this seven-day coverage percentage.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.
page Int - 1-based page number; defaults to 1. A page past the end returns empty `entries`.
perPage Int - Page size. Defaults to 20 and is capped at 100.
search String - Matches device name, IP address, MAC (any spelling) or serial, the same filter the fleet page and REST `?search=` apply.
siteId ID - Only devices at this site.
status String - Only devices in this status (`up`, `down` or `unknown`).
updatedSince String - Only devices whose `updated_at` is at or after this ISO 8601 instant are listed; `meta.window.until` echoes the request's `as_of`.

discoveredCandidates [DiscoveredCandidate]

Lists discovered device candidates awaiting review, one page at a time. Requires the `discovery:read` scope.

Argument Type Default Description
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.
page Int - 1-based page number.
perPage Int - Page size. Defaults to 20 and is capped at 100.

escalationPolicies [EscalationPolicy]

Lists the organization's escalation policies, each with its computed health. Requires the `config:read` scope.

Argument Type Default Description
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

escalationPolicy EscalationPolicy

Fetches a single escalation policy with its rules, their targets and the policy's computed health. Requires the `config:read` scope.

Argument Type Default Description
id ID! - ID of the escalation policy.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

integrations [Integration]

Lists the organization's third-party integrations, including each one's sync interval and last sync result. Requires the `integrations:read` scope.

Argument Type Default Description
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

interfaceTraffic [InterfaceTrafficPoint]

Traffic rates in bits per second for a network interface, computed from the deltas between SNMP counter samples, oldest first. Returns up to 120 points per hour of `timeRange` (43,200 rows maximum), matching the web charts. Requires the `devices:read` scope.

Argument Type Default Description
interfaceId ID! - ID of the interface.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.
timeRange String "24h" How far back to read, given in hours (`1h`, `24h`, `72h`). Clamped to 1-720 hours (30 days).

maintenanceWindow MaintenanceWindow

Fetches a single maintenance window by ID. Requires the `config:read` scope.

Argument Type Default Description
id ID! - ID of the maintenance window.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

maintenanceWindows [MaintenanceWindow]

Lists the organization's maintenance windows. Requires the `config:read` scope.

Argument Type Default Description
filter String - Restricts the list to `active`, `upcoming` or `past` windows; any other value returns them all.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

members [Member]

Lists the organization's members and their roles. Requires the `members:read` scope.

Argument Type Default Description
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

myOnCall MyOnCallStatus

The caller's own on-call standing, what the mobile app puts on screen.

Argument Type Default Description
horizonDays Int 14 How many days forward and back to search for the caller's shifts. Defaults to 14 and is capped at 90.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

myOrganizations [Organization]

Every organization the authenticated user belongs to, or, for an API or partner-app token, only the organization that token is scoped to. Takes no arguments and needs no organization scope, so it is the query a mobile client uses to populate an organization picker before it knows which organization to work in. Token callers need the `organization:read` scope since the result carries organization settings. `sitesCount`, `deviceCount` and `activeAlertsCount` are computed per row and are only populated by this query.

No arguments.

onCall OnCallResult

Who is on call for this schedule right now, or null when nobody is. Requires the `config:read` scope.

Argument Type Default Description
scheduleId ID! - ID of the schedule to evaluate.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

organization Organization

The caller's organization, including its SNMP and MikroTik defaults. Requires the `organization:read` scope.

Argument Type Default Description
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

schedule Schedule

Fetches a single on-call schedule with its layers, layer members and overrides preloaded. Requires the `config:read` scope.

Argument Type Default Description
id ID! - ID of the schedule.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

schedules [Schedule]

Lists the organization's on-call schedules. Requires the `config:read` scope.

Argument Type Default Description
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

sensorReadings [SensorReading]

Historical readings for a single SNMP sensor, newest first. Returns up to 120 points per hour of `timeRange` (43,200 rows maximum), matching the web charts. Requires the `devices:read` scope.

Argument Type Default Description
sensorId ID! - ID of the sensor.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.
timeRange String "24h" How far back to read, given in hours (`1h`, `24h`, `72h`). Clamped to 1-720 hours (30 days).

site Site

Fetches a single site by ID. Requires the `sites:read` scope.

Argument Type Default Description
id ID! - ID of the site.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

sites [Site]

Lists every site in the organization. Requires the `sites:read` scope.

Argument Type Default Description
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

Mutations

Write operations. Each requires the resource's write scope. As with queries, an API token's organization is implied; a mobile session passes organizationId to choose one.

EscalationPolicyInput supports alertTypes (persisted identifiers such as agent_offline or check_http), checkTypes (the check_ suffix, such as http), and nonnegative routingOrder. Each non-empty scope dimension must match; values within a list are alternatives. Omitted fields retain their values on update, while [] clears a list constraint. Explicit device policy assignment wins even if its scope refuses an alert. Otherwise, type-filtered non-default policies are tried by ascending routingOrder, creation time and ID; the first full-scope match wins, with the scoped organization default as fallback. Unfiltered non-default policies remain assignment-only. Missing device/site context bypasses only site and role constraints, not severity or type filters.

acknowledgeAlert Alert

Acknowledges an alert and records the acknowledging user. Requires the `alerts:write` scope.

Argument Type Default Description
id ID! - ID of the alert to acknowledge.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

addDiscoveredCandidate Device

Adds a discovered candidate to inventory as a managed device, prefilled with the identity discovery inferred. Requires the `discovery:write` scope.

Argument Type Default Description
identifier CandidateIdentifierInput! - The candidate's identifier, as returned by `discoveredCandidates`.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

addLayerMember LayerMember

Adds a user to a rotation layer. Requires the `config:write` scope.

Argument Type Default Description
layerId ID! - ID of the layer to add the user to.
position Int! - Where the user sits in the rotation order, counted from zero.
userId ID! - ID of the user joining the rotation.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

cancelInvitation DeleteResult

Cancels a pending invitation. Requires the `members:write` scope.

Argument Type Default Description
id ID! - ID of the invitation to cancel.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

createAgent AgentWithToken

Creates an agent for the organization and returns its raw token. The token is only ever returned here, so a client that loses it must create another agent. Requires the `agents:write` scope.

Argument Type Default Description
name String! - Display name for the new agent.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

createCheck Check

Creates a service check and schedules its first run when the check is enabled. Only `http`, `tcp`, `dns` and `ping` checks can be created here; any other type is rejected. Requires the `checks:write` scope.

Argument Type Default Description
input CheckInput! - Attributes for the new check, including its `checkType`, interval and type-specific `config`.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

createDevice Device

Creates a device in the caller's organization and returns it with its site preloaded. Requires the `devices:write` scope.

Argument Type Default Description
input DeviceInput! - Attributes for the new device; the organization is taken from the caller.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

createEscalationPolicy EscalationPolicy

Creates an escalation policy in the caller's organization. Requires the `config:write` scope.

Argument Type Default Description
input EscalationPolicyInput! - Attributes for the new policy, including alert/check type filters and automatic routing order.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

createEscalationRule EscalationRule

Adds a level to an escalation policy. Requires the `config:write` scope.

Argument Type Default Description
escalationPolicyId ID! - ID of the policy the rule belongs to.
input EscalationRuleInput! - Attributes for the new rule, such as its position in the ladder and how long it waits before the next level.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

createEscalationTarget EscalationTarget

Adds someone for an escalation rule to page: either a user directly or an on-call schedule. Requires the `config:write` scope.

Argument Type Default Description
escalationRuleId ID! - ID of the rule the target belongs to.
input EscalationTargetInput! - Attributes for the new target: its `targetType` plus the matching user or schedule.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

createIntegration Integration

Creates a third-party integration for the organization. Requires the `integrations:write` scope. Quo with `enabled: true` provisions its listener first. Failure returns an error and retains a disabled integration, which can be retrieved and updated to retry.

Argument Type Default Description
input IntegrationInput! - Attributes for the new integration, including its provider and credentials.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

createLayer Layer

Adds a rotation layer to a schedule. Requires the `config:write` scope.

Argument Type Default Description
input LayerInput! - Attributes for the new layer, such as its rotation type, interval, handoff time and start date.
scheduleId ID! - ID of the schedule the layer belongs to.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

createMaintenanceWindow MaintenanceWindow

Creates a maintenance window, recorded against the calling user, that can suppress alerts for a site or device while it runs. Requires the `config:write` scope.

Argument Type Default Description
input MaintenanceWindowInput! - Attributes for the new window: its span, what it covers and whether it suppresses alerts.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

createOverride Override

Creates an override that puts one user on call for a schedule over a fixed window, ahead of whatever the rotation would otherwise say. Requires the `config:write` scope.

Argument Type Default Description
input OverrideInput! - Attributes for the override: the user and the start and end of the window.
scheduleId ID! - ID of the schedule the override applies to.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

createSchedule Schedule

Creates an on-call schedule in the caller's organization. Requires the `config:write` scope.

Argument Type Default Description
input ScheduleInput! - Attributes for the new schedule, such as its name and timezone.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

createSite Site

Creates a site in the caller's organization. Requires the `sites:write` scope.

Argument Type Default Description
input SiteInput! - Attributes for the new site; the organization is taken from the caller.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

deleteAgent DeleteResult

Deletes an agent and reports whether the delete succeeded. Requires the `agents:write` scope.

Argument Type Default Description
id ID! - ID of the agent to delete.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

deleteCheck DeleteResult

Deletes a service check and reports whether the delete succeeded. Requires the `checks:write` scope.

Argument Type Default Description
id ID! - ID of the check to delete.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

deleteDevice DeleteResult

Deletes a device and reports whether the delete succeeded. Requires the `devices:write` scope.

Argument Type Default Description
id ID! - ID of the device to delete.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

deleteEscalationPolicy DeleteResult

Deletes an escalation policy and reports whether the delete succeeded. Requires the `config:write` scope.

Argument Type Default Description
id ID! - ID of the policy to delete.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

deleteEscalationRule DeleteResult

Deletes an escalation rule and reports whether the delete succeeded. Requires the `config:write` scope.

Argument Type Default Description
id ID! - ID of the rule to delete.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

deleteEscalationTarget DeleteResult

Removes a target from an escalation rule and reports whether the delete succeeded. Requires the `config:write` scope.

Argument Type Default Description
id ID! - ID of the target to delete.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

deleteIntegration DeleteResult

Deletes an integration and reports whether the delete succeeded. Requires the `integrations:write` scope.

Argument Type Default Description
id ID! - ID of the integration to delete.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

deleteLayer DeleteResult

Deletes a rotation layer and reports whether the delete succeeded. Requires the `config:write` scope.

Argument Type Default Description
id ID! - ID of the layer to delete.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

deleteMaintenanceWindow DeleteResult

Deletes a maintenance window and reports whether the delete succeeded. Requires the `config:write` scope.

Argument Type Default Description
id ID! - ID of the window to delete.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

deleteOverride DeleteResult

Deletes a schedule override and reports whether the delete succeeded. Requires the `config:write` scope.

Argument Type Default Description
id ID! - ID of the override to delete.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

deleteSchedule DeleteResult

Deletes an on-call schedule and reports whether the delete succeeded. Requires the `config:write` scope.

Argument Type Default Description
id ID! - ID of the schedule to delete.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

deleteSite DeleteResult

Deletes a site, every site under it, and their devices, and reports whether the delete succeeded. Requires the `sites:write` scope.

Argument Type Default Description
id ID! - ID of the site to delete.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

escalateAlert Alert

Pages the next on-call level immediately instead of waiting for the current level's timeout. Errors when the alert has no active escalation incident or the policy has no further level.

Argument Type Default Description
id ID! - ID of the alert to escalate.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

ignoreDiscoveredCandidate DeleteResult

Dismisses a discovered candidate so it stops resurfacing in review lists. Requires the `discovery:write` scope.

Argument Type Default Description
identifier CandidateIdentifierInput! - The candidate's identifier, as returned by `discoveredCandidates`.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

removeLayerMember DeleteResult

Removes a user from a rotation layer and reports whether the removal succeeded. Requires the `config:write` scope.

Argument Type Default Description
id ID! - ID of the layer membership to remove, not the user ID.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

removeMember DeleteResult

Removes a member from the organization. Owners cannot be removed, and only owners and admins may manage members. Requires the `members:write` scope.

Argument Type Default Description
id ID! - User ID of the member to remove.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

resolveAlert Alert

Marks an alert resolved. Requires the `alerts:write` scope.

Argument Type Default Description
id ID! - ID of the alert to resolve.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

sendInvitation Invitation

Invites an email address to join the organization. Only owners and admins may invite, and nobody may grant a role above their own. Requires the `members:write` scope.

Argument Type Default Description
email String! - Email address to invite.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.
role String "technician" Role to grant the invitee; defaults to `technician`.

snoozeAlert Alert

Silences an alert for `duration_minutes` without closing it. It leaves every active list and count, stops paging, and comes back by itself when the snooze lapses.

Argument Type Default Description
durationMinutes Int! - How long to silence the alert, in minutes.
id ID! - ID of the alert to snooze.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

testIntegration TestResult

Tests an integration's credentials and connectivity. The message is deliberately coarse, because upstream failure detail can carry credentials. Requires the `integrations:write` scope.

Argument Type Default Description
id ID! - ID of the integration to test.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

unsnoozeAlert Alert

Ends a snooze early, returning the alert to normal paging. Requires the `alerts:write` scope.

Argument Type Default Description
id ID! - ID of the snoozed alert.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

updateCheck Check

Updates editable service-check settings; the check type is immutable. Requires the `checks:write` scope.

Argument Type Default Description
id ID! - ID of the check to update.
input CheckInput! - Attributes to change; fields left out keep their stored values.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

updateDevice Device

Updates a device in the caller's organization. Requires the `devices:write` scope.

Argument Type Default Description
id ID! - ID of the device to update.
input DeviceInput! - Attributes to change; fields left out keep their stored values.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

updateEscalationPolicy EscalationPolicy

Updates an escalation policy. Requires the `config:write` scope.

Argument Type Default Description
id ID! - ID of the policy to update.
input EscalationPolicyInput! - Attributes to change; omitted fields keep stored values, empty scope lists clear their constraints, and routingOrder 0 restores the default order.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

updateEscalationRule EscalationRule

Updates an escalation rule. Requires the `config:write` scope.

Argument Type Default Description
id ID! - ID of the rule to update.
input EscalationRuleInput! - Attributes to change; fields left out keep their stored values.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

updateIntegration Integration

Updates an integration. Credentials left out of the input keep their stored values. Requires the `integrations:write` scope. Enabling Quo provisions its listener first; failure returns an error and leaves capture disabled. Replacing its API key first removes the previous workspace's subscription. Failed cleanup keeps the old credentials for retry. Subscription ids and signing keys are system-owned.

Argument Type Default Description
id ID! - ID of the integration to update.
input IntegrationInput! - Attributes to change; fields left out keep their stored values.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

updateLayer Layer

Updates a rotation layer. Requires the `config:write` scope.

Argument Type Default Description
id ID! - ID of the layer to update.
input LayerInput! - Attributes to change; fields left out keep their stored values.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

updateMaintenanceWindow MaintenanceWindow

Updates a maintenance window. Requires the `config:write` scope.

Argument Type Default Description
id ID! - ID of the window to update.
input MaintenanceWindowInput! - Attributes to change; fields left out keep their stored values.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

updateMemberRole Member

Changes a member's role. The owner's role cannot be changed, only owners may grant the owner role, and nobody may assign a role above their own. Requires the `members:write` scope.

Argument Type Default Description
id ID! - User ID of the member whose role changes.
role String! - Role to assign.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

updateMemberSites Member

Replaces a member's site restriction (issue 1775): the complete list of sites the member may see, `[]` lifts the restriction back to the whole organization. The owner's access cannot be restricted, and a caller whose own membership is site-scoped can only grant sites inside their own list. Requires the `members:write` scope.

Argument Type Default Description
id ID! - User ID of the member whose site restriction changes.
siteIds [ID!]! - Complete list of site IDs the member may see; `[]` is unrestricted.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

updateOrganization Organization

Updates the caller's organization, including its SNMP and MikroTik defaults. Requires the `organization:write` scope.

Argument Type Default Description
input OrganizationInput! - Organization settings to change; fields left out keep their stored values.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

updateSchedule Schedule

Updates an on-call schedule. Requires the `config:write` scope.

Argument Type Default Description
id ID! - ID of the schedule to update.
input ScheduleInput! - Attributes to change; fields left out keep their stored values.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

updateSite Site

Updates a site in the caller's organization. Requires the `sites:write` scope.

Argument Type Default Description
id ID! - ID of the site to update.
input SiteInput! - Attributes to change; fields left out keep their stored values.
organizationId ID - Ignored for API-token callers, whose organization comes from the token; mobile sessions must pass it.

Subscriptions

Subscribe to real-time events via WebSocket. Connect to wss://staging.towerops.net/socket/graphql with your API token as a connection parameter. Each subscription requires the resource's read scope: devices:read for device status and sensor readings, alerts:read for alert events.

Connecting
// JavaScript example using @absinthe/socket
import { Socket as PhoenixSocket } from "phoenix";
import * as AbsintheSocket from "@absinthe/socket";

const phoenixSocket = new PhoenixSocket(
  "wss://staging.towerops.net/socket/graphql",
  { params: { token: "your-api-token" } }
);
const absintheSocket = AbsintheSocket.create(phoenixSocket);

alertEvent AlertEvent

Alert lifecycle events - created, acknowledged, resolved - for the organization, delivered over the `ToweropsWeb.GraphQLSocket` websocket. Requires the `alerts:read` scope.

Argument Type Default Description
organizationId ID - Ignored for API-token connections, whose organization comes from the token; mobile sessions must pass it.

deviceStatusChanged DeviceStatusEvent

Device status changes in the organization, delivered over the `ToweropsWeb.GraphQLSocket` websocket. Requires the `devices:read` scope.

Argument Type Default Description
deviceId ID - Only events for this device; omit it to watch every device in the organization.
organizationId ID - Ignored for API-token connections, whose organization comes from the token; mobile sessions must pass it.

sensorReadingsUpdated SensorReadingsEvent

Live sensor readings for one device, delivered in batches over the `ToweropsWeb.GraphQLSocket` websocket as they are polled. Requires the `devices:read` scope.

Argument Type Default Description
deviceId ID! - ID of the device to stream readings for.
organizationId ID - Ignored for API-token connections, whose organization comes from the token; mobile sessions must pass it.

Types

The object, input and scalar types published for integration, the schema's internal types are not listed here. A trailing ! means non-null; brackets mean a list.

ActivityItem object

Field Type Description
detail String
deviceName String
icon String
link String
severity String
siteName String
summary String
timestamp String
type String

ActivityPage object

Field Type Description
entries [ActivityItem]! The page's activity items, in the collection order (timestamp, then type name, then row id).
meta PageMeta! Page metadata. The feed has no time-window parameter, so `meta.window` is always null.

Agent object

Field Type Description
allowRemoteDebug Boolean
deviceCount Int
enabled Boolean
expiresAt String
id ID
insertedAt String
isCloudPoller Boolean
lastIp String
lastSeenAt String
metadata Json
name String
organizationId ID
updatedAt String

AgentWithToken object

Field Type Description
enabled Boolean
expiresAt String
id ID
insertedAt String
name String
token String

Alert object

Field Type Description
acknowledgedAt String
acknowledgedByEmail String
acknowledgedById ID
alertType String
device Device
deviceId ID
escalation AlertEscalation Current on-call escalation state, or null when this alert has no active incident, no policy, PagerDuty-only routing, or already resolved. Batched across the result set: selecting it on the `alerts` list costs two queries for the whole page, not one lookup per row.
id ID
insertedAt String
message String
notifications [AlertNotification] Ordered page timeline: every recorded delivery attempt for the alert's escalation incidents, who was paged, on which channel, at which level, and whether it landed. Includes `held`, `skipped` and `failed` rows for the deliveries that never went out. Batched like `escalation`: one query per page of alerts, not per row.
platformDegraded Boolean True when TowerOps was degraded at alert creation. This historical flag remains true after platform recovery; it is not the platform's current health.
resolvedAt String
severity Int Effective severity: 2 = critical, 1 = warning, null = informational. Mirrors the server's own criticality rule rather than the raw column, so `device_down`, `site_outage` and `agent_offline` report 2 even when `alerts.severity` is null, the same alerts the web UI paints red.
snoozedByEmail String
snoozedUntil String
status String Server-derived lifecycle status: "resolved", "acknowledged" or "active". Clients should render this instead of re-deriving it from the timestamps.
subscriberImpact Json Stored subscriber counts and identities, or null when no snapshot exists. Revenue fields require financial visibility in this alert's organization; the same rule applies to query and mutation results.
triggeredAt String
updatedAt String

AlertEscalation object

On-call escalation progress for an alert.

Field Type Description
canEscalate Boolean True while the incident has a surviving rule, a stopped chain stays manually escalatable.
incidentStatus String Incident status: "triggered", "acknowledged" or "resolved".
level Int 1-based level the incident is currently paging.
loop Int 1-based pass through the policy, for policies that repeat.
maxLevel Int How many levels the policy has.
maxLoop Int Paging ceiling in hours (policy repeat_count), not a loop cap.
pagingDeadline String When the chain stops paging if nobody acknowledges first (ISO 8601).
pagingStoppedAt String When the chain stopped paging because its ceiling passed unacknowledged (ISO 8601).
policyName String

AlertEvent object

Field Type Description
alertId ID
alertType String
deviceId ID
eventType String
message String
severity Int Effective severity: 2 = critical, 1 = warning, null = informational.
triggeredAt String

AlertNotification object

One recorded page attempt against an on-call incident.

Field Type Description
channel String Delivery channel: "email", "push", "sms" or "phone".
errorMessage String Why the delivery was held, skipped or failed.
id ID
insertedAt String
level Int 1-based escalation level the attempt belongs to.
sentAt String
status String Outcome: "sent", "failed", "held" or "skipped".
targetEmail String Email of the paged user, for display.
userId ID

AlertPage object

Field Type Description
entries [Alert]! The page's alerts, in the collection order (`triggered_at`, then id, both descending).
meta PageMeta! Page metadata and the `triggeredAt` window this page and its `totalCount` were read from.

CandidateIdentifier object

Field Type Description
type String! The sighting key kind: `mac`, `ip` or `hostname`.
value String! The normalized identifier value.

CandidateSighting object

Field Type Description
deviceId ID
deviceName String
interface String
timestamp String

Check object

Field Type Description
agentTokenId ID
alerting Boolean
checkType String
config Json
currentState Int
currentStateType String
description String
deviceId ID
enabled Boolean
id ID
insertedAt String
intervalSeconds Int Execution interval in seconds (minimum 30).
lastCheckAt String
maxCheckAttempts Int
name String
retryIntervalSeconds Int Interval between retries in a soft state, in seconds (minimum 30).
timeoutMs Int Per-attempt timeout in milliseconds (1-30000).

CheckResultPoint object

Field Type Description
checkId ID
checkedAt String
responseTimeMs Float
status Int
value Float

CollectionWindow object

Field Type Description
asOf String The instant this request's window was captured (ISO 8601).
field String The timestamp column the window bounds (`updated_at` or `triggered_at`).
mode String `all` when no bound was requested, `recent` for the default seven-day-or-unresolved alert window, `range` for an explicit bound.
since String Inclusive lower bound (ISO 8601), or null when the window is open below.
until String Inclusive upper bound (ISO 8601), or null when the window is open above. A lower bound sent without an upper bound closes at `asOf`.

DeleteResult object

Field Type Description
message String
success Boolean!

Device object

Field Type Description
checkIntervalSeconds Int
description String
deviceRole String
displayOrder Int
eolOn String
id ID
insertedAt String
ipAddress String
lastCheckedAt String
lastDiscoveryAt String
lastSnmpPollAt String
lastStatusChangeAt String
mikrotikCredentialSource String
mikrotikEnabled Boolean
mikrotikPort Int
mikrotikSshPort Int
mikrotikUseSsl Boolean
mikrotikUsername String
monitoringEnabled Boolean
monitoringHistory DeviceMonitoringHistory! Durable 24-hour and seven-day polling evidence, retained after recovery.
name String
organizationId ID
purchasedOn String
site Site
siteId ID
snmpCommunitySet Boolean
snmpCommunitySource String
snmpEnabled Boolean
snmpPort Int
snmpTransport String
snmpTransportSource String
snmpVersion String
snmpv3AuthProtocol String
snmpv3CredentialSource String
snmpv3PrivProtocol String
snmpv3SecurityLevel String
snmpv3Username String
status String
updatedAt String
warrantyExpiresOn String

DeviceMonitoringGap object

Field Type Description
durationSeconds Int!
endedAt String!
startedAt String!

DeviceMonitoringHistory object

Field Type Description
lastDay DeviceMonitoringWindow! Coverage and the longest recovered gap during the last 24 hours.
lastWeek DeviceMonitoringWindow! Coverage and the longest recovered gap during the last seven days.
recentPollFailures [DevicePollFailure!]!
recentPollGaps [DeviceMonitoringGap!]!

DeviceMonitoringWindow object

Field Type Description
coveragePercent Float!
expected Int!
from String!
hasData Boolean!
longestGap DeviceMonitoringGap
observed Int!
to String!

DevicePage object

Field Type Description
entries [Device]! The page's devices, in the collection order (display_order, name, id).
meta PageMeta! Page metadata and the `updatedAt` window this page and its `totalCount` were read from.

DevicePollFailure object

Field Type Description
id ID!
message String!
startedAt String!

DeviceStatusEvent object

Field Type Description
changedAt String
deviceId ID
deviceName String
status String

DiscoveredCandidate object

Field Type Description
capabilities [String]
deviceCount Int Distinct managed devices that reported this identifier.
deviceType String The inferred `Towerops.Discovery.Class` class.
discoveredBy [CandidateSighting]
hostname String
identifier CandidateIdentifier! The identifier the add/ignore mutations take back.
ipAddresses [String]
lastSeen String
macAddresses [String]
manufacturer String
platform String
protocolsUsed [String]
sourceCount Int

EscalationPolicy object

A paging policy. All non-empty scope dimensions must match; values within each list are alternatives. Missing device/site context bypasses only the site and role constraints, not severity or type filters. Explicit device assignment wins, even if the policy refuses the alert. Otherwise type-filtered, non-default policies are tried by routingOrder, creation time and ID; the first full-scope match wins. Unfiltered non-default policies remain assignment-only. The organization's default is the fallback, with its constraints enforced.

Field Type Description
alertTypes [String] Persisted alert types this policy pages for; an empty list is unconstrained.
checkTypes [String] Check types derived from the check_ alert-type suffix; an empty list is unconstrained.
description String
deviceRoles [String]
health String `"ok"`, `"no_levels"`, `"levels_without_targets"` or `"levels_without_recipients"`, whether this policy can page anyone.
id ID
insertedAt String
minimumSeverity Int
name String
organizationId ID
repeatCount Int
routingOrder Int Nonnegative automatic routing priority; lower values win, then creation time and ID.
rules [EscalationRule]
siteIds [ID]
updatedAt String

EscalationRule object

Field Type Description
escalationPolicyId ID
id ID
insertedAt String
position Int
targets [EscalationTarget]
timeoutMinutes Int

EscalationTarget object

Field Type Description
escalationRuleId ID
id ID
insertedAt String
role String Membership role paged when `targetType` is "role".
scheduleId ID
scheduleName String Set when `targetType` is "schedule".
targetType String
user OnCallUser Set when `targetType` is "user".
userId ID

Integration object

Field Type Description
enabled Boolean
id ID
insertedAt String
lastSyncStatus String
lastSyncedAt String
organizationId ID
provider String
syncIntervalMinutes Int
updatedAt String

Interface object

Field Type Description
id ID
ifAdminStatus String
ifAlias String
ifDescr String
ifIndex Int
ifName String
ifOperStatus String
ifSpeed Float
ifType String

InterfaceTrafficPoint object

Field Type Description
inBps Float
inErrors Int
outBps Float
outErrors Int
timestamp String

Invitation object

Field Type Description
acceptedAt String
email String
expiresAt String
id ID
insertedAt String
role String

Layer object

Field Type Description
handoffDay Int Weekday 0 (Sunday)-6 (Saturday) in the schedule's timezone, required for `weekly` rotations.
handoffTime String Time of day the rotation hands off, `HH:MM:SS`, in the schedule's timezone.
id ID
insertedAt String
members [LayerMember]
name String
position Int
restrictionType String
restrictions Json Restriction window, e.g. `{"start_time": "08:00", "end_time": "17:00", "days": [1,2,3,4,5]}`.
rotationInterval Int
rotationType String
startDate String

LayerMember object

Field Type Description
id ID
insertedAt String
layerId ID
position Int
user OnCallUser
userId ID

MaintenanceWindow object

Field Type Description
announceOnStatusPage Boolean
deviceId ID
endsAt String
excludeFromUptime Boolean
id ID
insertedAt String
name String
organizationId ID
publicTitle String
reason String
recurrenceRule String
recurring Boolean
siteId ID
startsAt String
suppressAlerts Boolean
updatedAt String

Member object

Field Type Description
email String
id ID
insertedAt String
isDefault Boolean
role String
siteIds [ID] Site restriction: the sites this member may see - empty means organization-wide.
userId ID

MetricPoint object

Field Type Description
checkName String
checkType String
status Int
timestamp String
value Float

MyOnCallSchedule object

Field Type Description
currentShift OnCallShift
nextShift OnCallShift
onCallNow Boolean
scheduleId ID
scheduleName String
timezone String

MyOnCallStatus object

The caller's own on-call standing across an organization's schedules.

Field Type Description
currentShift OnCallShift The caller's active shift running latest, what "on call until" means.
nextShift OnCallShift The caller's soonest shift starting after now, within the horizon.
onCallNow Boolean True when the caller is on call on at least one schedule right now.
schedules [MyOnCallSchedule] Every schedule the caller participates in, on call or not.

OnCallResult object

Field Type Description
email String
userId ID

OnCallShift object

One unbroken stretch of on-call duty.

Field Type Description
endAt String
startAt String
user OnCallUser

OnCallUser object

A person who can be paged, with a label that is safe to render as-is.

Field Type Description
displayName String "First Last" when both are set, otherwise the email address.
email String
firstName String
id ID
lastName String

Organization object

Field Type Description
activeAlertsCount Int
defaultAgentTokenId ID
deviceCount Int
devicesDownCount Int
devicesUpCount Int
id ID
insertedAt String
mikrotikEnabled Boolean
mikrotikPort Int
mikrotikSshPort Int
mikrotikUseSsl Boolean
mikrotikUsername String
name String
sitesCount Int
slug String
snmpCommunitySet Boolean
snmpPort Int
snmpTransport String
snmpVersion String
snmpv3AuthProtocol String
snmpv3PrivProtocol String
snmpv3SecurityLevel String
snmpv3Username String
subscriptionPlan String
temperatureUnits String
updatedAt String
useSites Boolean
weatherUnits String

Override object

Field Type Description
acceptedAt String When the named cover accepted. Null means pending.
endTime String
id ID
insertedAt String
pending Boolean True while this row is a swap request awaiting the cover's accept.
reason String Why the requester asked for cover, as they wrote it.
requestedBy OnCallUser The member who asked for this swap. Null on a plain override.
requestedById ID The member who asked for this swap. Null on a plain override.
scheduleId ID
startTime String
user OnCallUser
userId ID

PageMeta object

Field Type Description
page Int 1-based page number of this page.
perPage Int Page size in effect; `perPage` defaults to 20 and is capped at 100.
totalCount Int Total rows matching the request's filters inside its window.
totalPages Int Total number of pages at this page size.
window CollectionWindow The time window this page's rows and `totalCount` were read from, or null where the collection has no window (`activityPage`).

Schedule object

Field Type Description
currentOnCall OnCallUser Who is on call right now. Null when nothing covers this instant.
description String
id ID
insertedAt String
layers [Layer]
name String
nextHandoffAt String The next instant the on-call user changes. Null when it never does.
organizationId ID
overrides [Override]
timeline [OnCallShift] Contiguous on-call shifts between two instants, overrides applied. Adjacent shifts for the same person are merged and uncovered gaps are omitted, so the result is exactly what the web timeline draws.
timezone String
updatedAt String

Sensor object

Field Type Description
currentValue Float
id ID
lastCheckedAt String
monitored Boolean
sensorDescr String
sensorType String
sensorUnit String

SensorReading object

Field Type Description
checkedAt String
sensorId ID
status String
value Float

SensorReadingSnapshot object

Field Type Description
checkedAt String
sensorDescr String
sensorId ID
sensorType String
sensorUnit String
value Float

SensorReadingsEvent object

Field Type Description
deviceId ID
deviceName String
readings [SensorReadingSnapshot]

Site object

Field Type Description
address String
agentTokenId ID
description String
displayOrder Int
id ID
insertedAt String
latitude Float
location String
longitude Float
mikrotikEnabled Boolean
mikrotikPort Int
mikrotikSshPort Int
mikrotikUseSsl Boolean
mikrotikUsername String
name String
organizationId ID
parentSiteId ID
snmpCommunitySet Boolean
snmpPort Int
snmpTransport String
snmpVersion String
snmpv3AuthProtocol String
snmpv3PrivProtocol String
snmpv3SecurityLevel String
snmpv3Username String
updatedAt String

TestResult object

Field Type Description
message String
success Boolean!

CandidateIdentifierInput input

Field Type Description
type String! The sighting key kind: `mac`, `ip` or `hostname`.
value String! The normalized identifier value.

CheckInput input

Field Type Description
agentTokenId ID
checkType String Service type for creation (HTTP, TCP, DNS or ping); ignored when updating a check.
config Json
description String
deviceId ID
enabled Boolean
intervalSeconds Int Execution interval in seconds (minimum 30).
maxCheckAttempts Int
name String
retryIntervalSeconds Int Interval between retries in a soft state, in seconds (minimum 30).
timeoutMs Int Per-attempt timeout in milliseconds (1-30000).

DeviceInput input

Field Type Description
checkIntervalSeconds Int
description String
deviceRole String
eolOn String
ipAddress String
mikrotikEnabled Boolean
mikrotikPassword String
mikrotikPort Int
mikrotikSshPort Int
mikrotikUseSsl Boolean
mikrotikUsername String
monitoringEnabled Boolean
name String
parentDeviceId ID
purchasedOn String
siteId ID
snmpCommunity String
snmpEnabled Boolean
snmpPort Int
snmpTransport String
snmpVersion String
snmpv3AuthPassword String
snmpv3AuthProtocol String
snmpv3PrivPassword String
snmpv3PrivProtocol String
snmpv3Username String
warrantyExpiresOn String

EscalationPolicyInput input

Field Type Description
alertTypes [String] Restrict paging to emitted alert classes (e.g. agent_offline, check_http). A value outside the catalog is rejected, declare it in customAlertTypes instead. An empty list clears the constraint; omission on update preserves it.
checkTypes [String] Restrict paging to the check_ alert-type suffix (e.g. http); registry check types only, every check alert carries one. An empty list clears the constraint; omission on update preserves it. All non-empty scope dimensions must match.
customAlertTypes [String] Alert classes the product does not emit, e.g. an SNMP trap rule's class. Declared here they are admitted into alertTypes on save. Omission on update preserves stored classes.
description String
deviceRoles [String] Restrict paging to device roles ("router", "switch", "access_point", "backhaul", "server", "other"). An empty list clears the constraint; omission on update preserves it.
minimumSeverity Int Lowest alert severity this policy pages for (1 = warning, 2 = critical). Omit on create or send null for any severity; omission on update preserves the floor.
name String
repeatCount Int
routingOrder Int Nonnegative automatic routing priority (default 0 on create); lower values win, then creation time and ID. Omission on update preserves it.
siteIds [ID] Restrict paging to same-organization sites. An empty list clears the constraint; omission on update preserves it.

EscalationRuleInput input

Field Type Description
position Int Step order within the policy. Omit to append the rule as the last step. A position another step already uses is rejected, because steps are never renumbered: an in-flight escalation tracks the position it is on. Change a rule's position with `updateEscalationRule`.
timeoutMinutes Int Minutes to wait at this step before escalating.

EscalationTargetInput input

Field Type Description
role String Membership role to page, when `targetType` is "role". One of "owner", "admin", "executive", "technician" or "viewer"; the retired "member" role is rejected.
scheduleId ID
targetType String One of "user", "schedule" or "role".
userId ID

IntegrationInput input

Field Type Description
credentials Json
enabled Boolean
provider String
syncIntervalMinutes Int

LayerInput input

Field Type Description
handoffDay Int Weekday 0 (Sunday)-6 (Saturday) in the schedule's timezone, required for `weekly` rotations.
handoffTime String Time of day the rotation hands off, `HH:MM:SS`, in the schedule's timezone.
name String
position Int
restrictionType String
restrictions Json
rotationInterval Int
rotationType String
startDate String

MaintenanceWindowInput input

Field Type Description
announceOnStatusPage Boolean Publicly announce the window's public title and end time on mapped status components. Defaults to false; true opts in.
deviceId ID
endsAt String
excludeFromUptime Boolean
name String
publicTitle String Customer-facing label used when the window is announced; the internal name is never published.
reason String
recurrenceRule String
recurring Boolean
siteId ID
startsAt String
suppressAlerts Boolean

OrganizationInput input

Field Type Description
defaultAgentTokenId ID
mikrotikEnabled Boolean
mikrotikPassword String
mikrotikPort Int
mikrotikSshPort Int
mikrotikUseSsl Boolean
mikrotikUsername String
name String
snmpCommunity String
snmpPort Int
snmpTransport String
snmpVersion String
snmpv3AuthPassword String
snmpv3AuthProtocol String
snmpv3PrivPassword String
snmpv3PrivProtocol String
snmpv3Username String
temperatureUnits String
useSites Boolean
weatherUnits String

OverrideInput input

Field Type Description
endTime String
startTime String
userId ID

ScheduleInput input

Field Type Description
description String
name String
timezone String

SiteInput input

Field Type Description
agentTokenId ID
description String
location String
mikrotikEnabled Boolean
mikrotikPassword String
mikrotikPort Int
mikrotikSshPort Int
mikrotikUseSsl Boolean
mikrotikUsername String
name String
parentSiteId ID
snmpCommunity String
snmpPort Int
snmpTransport String
snmpVersion String
snmpv3AuthPassword String
snmpv3AuthProtocol String
snmpv3PrivPassword String
snmpv3PrivProtocol String
snmpv3Username String

Boolean scalar

The `Boolean` scalar type represents `true` or `false`.

Float scalar

The `Float` scalar type represents signed double-precision fractional values as specified by [IEEE 754](https://en.wikipedia.org/wiki/IEEE_754).

ID scalar

The `ID` scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `"4"`) or integer (such as `4`) input value will be accepted as an ID.

Int scalar

The `Int` scalar type represents non-fractional signed whole numeric values. It is NOT compliant with the GraphQl spec, it can represent values between `-(2^53 - 1)` and `2^53 - 1` as specified by [IEEE 754](https://en.wikipedia.org/wiki/IEEE_754). It is kept here for backwards compatibility, prefer using the SpecCompliantInt.

Json scalar

Arbitrary JSON data. Accepts a JSON-encoded string, or a native GraphQL object literal (or a variable of the equivalent shape), whose nested values may themselves be lists, e.g. both `config: "{\"url\": \"...\"}"` and `config: {url: "...", tags: ["a", "b"]}` are valid for a `:json`-typed argument. A bare top-level list literal is not, per the GraphQL scalar grammar. Output is always the decoded native value (map, list, string, number, boolean or null), never a re-encoded string.

String scalar

The `String` scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

curl Examples

List devices with site info

curl -X POST https://staging.towerops.net/api/graphql \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ devices(limit: 50) { id name ipAddress status site { id name location } } }"}'

Get active alerts

curl -X POST https://staging.towerops.net/api/graphql \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ alerts(status: \"active\", limit: 50) { id alertType message triggeredAt device { name ipAddress } } }"}'

Create a device

curl -X POST https://staging.towerops.net/api/graphql \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { createDevice(input: { ipAddress: \"192.168.1.1\", name: \"Core Router\", snmpEnabled: true }) { id name status } }"}'

Acknowledge an alert

curl -X POST https://staging.towerops.net/api/graphql \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { acknowledgeAlert(id: \"alert-uuid\") { id acknowledgedAt } }"}'

Using variables

curl -X POST https://staging.towerops.net/api/graphql \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "query GetDevice($id: ID!) { device(id: $id) { id name ipAddress status site { name } } }", "variables": {"id": "device-uuid"}}'