Help

GraphQL API

The GraphQL API lets you query exactly the data you need in a single request. The endpoint is POST /api/graphql and authenticates with the same Bearer tokens as the rest of the API: an organization API token, a partner app access token, or a mobile session token.

Why GraphQL?

• Fetch related data in one query: Get devices with their sites, alerts, and latest metrics in a single request
• No over-fetching: Request only the fields you need
• Scoped access: API tokens carry scopes, and each field requires the scope it reads

Quick Example

# create a token in Account Settings → API tab
curl -X POST https://staging.towerops.net/api/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ devices { id name ipAddress status } }"}'

Available Queries

• devices / device: Devices with filtering, nested site data, and single-device detail
• sites / site: Sites with nested device lists
• alerts / alert: Active and historical alerts with device context
• checks / check: Service checks and their configuration
• agents / agent: Remote poller agents
• deviceMetrics / deviceInterfaces / deviceSensors / sensorReadings / interfaceTraffic / checkResults: Time-series readings for devices, interfaces, sensors, and checks
• schedules / schedule / onCall / myOnCall: On-call schedules and who is on call now
• escalationPolicies / escalationPolicy: Escalation policies with their computed health
• maintenanceWindows / maintenanceWindow: Planned maintenance windows
• organization / members / integrations / activity / myOrganizations: Organization settings, membership, integrations, and recent activity

Mutations

• createDevice / updateDevice / deleteDevice: Manage devices

  createDevice answers two structured errors a client can branch on: a duplicate IP at the site carries code 'conflict' with field 'ipAddress', and a plan device cap carries code 'plan_limit' with current, limit and upgrade_url details. Other validation failures arrive as a plain message.

• createSite / updateSite / deleteSite: Manage sites
• createCheck / updateCheck / deleteCheck: Manage service checks
• acknowledgeAlert / resolveAlert / snoozeAlert / unsnoozeAlert / escalateAlert: Alert lifecycle management
• createIntegration / updateIntegration / deleteIntegration / testIntegration: Manage vendor integrations
• createSchedule / createLayer / addLayerMember / createOverride / createEscalationPolicy / createEscalationRule / createEscalationTarget: Manage on-call schedules and escalation policies
• createMaintenanceWindow / updateMaintenanceWindow / deleteMaintenanceWindow: Manage maintenance windows

  MaintenanceWindowInput.announceOnStatusPage defaults to false; set true to opt in. Finite windows publicly announce their publicTitle (or 'Scheduled maintenance' when blank) and end time on mapped status components until maintenance ends; the internal window name is never published. Windows with no mapped components make no public changes.

• createAgent / deleteAgent / sendInvitation / cancelInvitation / removeMember / updateMemberRole / updateOrganization: Manage pollers, membership, and organization settings

Subscriptions

The GraphQL WebSocket at /socket/graphql streams live updates as subscription fields: deviceStatusChanged, alertEvent, and sensorReadingsUpdated. It accepts the same token types as the HTTP endpoint, passed as a token connect parameter.