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 <.link navigate={~p"/docs/api"} class="text-blue-600 hover:text-blue-500 dark:text-blue-400">REST API and provides equivalent functionality with the added benefit of nested queries and precise field selection.

Authentication

Authenticate using a Bearer token in the Authorization header. API tokens can be created in your organization settings. 

Authorization: Bearer <%= @sample_token %>

Endpoint

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

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

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

curl -X POST https://app.towerops.net/api/graphql \
  -H "Authorization: Bearer <%= @sample_token %>" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ devices { id name ipAddress status } }"}'

Query: Devices

devices

List all devices. Optionally filter by site or status.

Argument Type Description
siteIdIDFilter by site
statusStringFilter by status (up, down, unknown)
limitIntMax results (default: 100)
 
{
  devices(siteId: "uuid", status: "up") {
    id
    name
    ipAddress
    status
    lastCheckedAt
    monitoringEnabled
    snmpEnabled
    deviceRole
    site {
      id
      name
      location
    }
  }
}

device

Get a single device by ID.

{
  device(id: "device-uuid") {
    id
    name
    ipAddress
    status
    description
    snmpVersion
    snmpPort
    checkIntervalSeconds
    site { id name }
  }
}

Query: Sites

sites

List all sites for the organization.

{
  sites {
    id
    name
    description
    location
    snmpVersion
    snmpCommunity
    insertedAt
  }
}

site

Get a single site by ID.

{ site(id: "site-uuid") { id name location } }

Query: Alerts

alerts

List alerts. Filter by status or device.

Argument Type Description
statusStringactive, acknowledged, or resolved
deviceIdIDFilter by device
limitIntMax results (default: 100)
 
{
  alerts(status: "active", limit: 10) {
    id
    alertType
    message
    triggeredAt
    acknowledgedAt
    resolvedAt
    deviceId
    device {
      id
      name
      ipAddress
    }
    acknowledgedByEmail
  }
}

Query: Agents

{
  agents {
    id
    name
    enabled
    lastSeenAt
    lastIp
    isCloudPoller
    deviceCount
    metadata
  }
}

# Single agent
{ agent(id: "agent-uuid") { id name enabled deviceCount } }

Query: Organization

{
  organization {
    id
    name
    slug
    subscriptionPlan
    useSites
    snmpVersion
    snmpCommunity
    snmpPort
    snmpTransport
    mikrotikEnabled
    mikrotikUsername
    mikrotikPort
    mikrotikUseSsl
    defaultAgentTokenId
  }
}

Query: Members

{
  members {
    id
    email
    role
    insertedAt
  }
}

Query: Integrations

{
  integrations {
    id
    provider
    enabled
    syncIntervalMinutes
    lastSyncedAt
    lastSyncStatus
  }
}

Query: Activity

{
  activity(limit: 20) {
    summary
    detail
    timestamp
    severity
    deviceName
    siteName
    link
    type
  }
}

Query: Metrics & Interfaces

deviceMetrics

Get time-series metrics for a device.

Argument Type Description
deviceIdID!Required device ID
sensorTypeStringFilter by sensor type
timeRangeStringe.g. "24h", "72h" (default: "24h")
 
{
  deviceMetrics(deviceId: "device-uuid", timeRange: "48h") {
    timestamp
    value
    status
    checkName
    checkType
  }
}

deviceInterfaces

Get SNMP interfaces for a device.

{
  deviceInterfaces(deviceId: "device-uuid") {
    id
    ifIndex
    ifName
    ifDescr
    ifType
    ifSpeed
    ifAdminStatus
    ifOperStatus
    ifAlias
  }
}

Mutation: Devices

createDevice

mutation {
  createDevice(input: {
    ipAddress: "192.168.1.1"
    name: "Core Router"
    siteId: "site-uuid"
    snmpEnabled: true
    snmpVersion: "2c"
    snmpCommunity: "public"
  }) {
    id
    name
    ipAddress
    status
  }
}

updateDevice

mutation {
  updateDevice(id: "device-uuid", input: {
    name: "Updated Router"
    monitoringEnabled: false
  }) {
    id
    name
    monitoringEnabled
  }
}

deleteDevice

mutation {
  deleteDevice(id: "device-uuid") {
    success
    message
  }
}

Mutation: Sites

createSite

mutation {
  createSite(input: {
    name: "Main Office"
    location: "New York, NY"
    snmpCommunity: "public"
  }) {
    id
    name
    location
  }
}

updateSite / deleteSite

Same pattern as device mutations.

Mutation: Alert Actions

acknowledgeAlert

mutation {
  acknowledgeAlert(id: "alert-uuid") {
    id
    acknowledgedAt
    acknowledgedByEmail
  }
}

resolveAlert

mutation {
  resolveAlert(id: "alert-uuid") {
    id
    resolvedAt
  }
}

Mutation: Agent Management

createAgent

Creates a new agent token. The raw token is only returned once.

mutation {
  createAgent(name: "DC1 Agent") {
    id
    name
    token
  }
}

deleteAgent

mutation { deleteAgent(id: "agent-uuid") { success message } }

Mutation: Organization Settings

mutation {
  updateOrganization(input: {
    name: "My Network"
    useSites: true
    snmpVersion: "2c"
    snmpCommunity: "public"
    mikrotikEnabled: true
    mikrotikUsername: "admin"
    mikrotikPort: 8729
    mikrotikUseSsl: true
  }) {
    id
    name
    useSites
    snmpVersion
    mikrotikEnabled
  }
}

Mutation: Members

sendInvitation

mutation {
  sendInvitation(email: "user@example.com", role: "admin") {
    id
    email
    role
    expiresAt
  }
}

updateMemberRole

mutation {
  updateMemberRole(id: "user-uuid", role: "admin") {
    id
    email
    role
  }
}

removeMember / cancelInvitation

mutation { removeMember(id: "user-uuid") { success message } }
mutation { cancelInvitation(id: "invitation-uuid") { success message } }

Mutation: Integrations

createIntegration

mutation {
  createIntegration(input: {
    provider: "preseem"
    enabled: true
    credentials: "{\"api_key\": \"xxx\"}"
    syncIntervalMinutes: 10
  }) {
    id
    provider
    enabled
  }
}

testIntegration

mutation {
  testIntegration(id: "integration-uuid") {
    success
    message
  }
}

Types Reference

All field names use camelCase in GraphQL queries (Absinthe automatically converts from Elixir's snake_case).

Device

id, name, ipAddress, description, displayOrder, status, lastCheckedAt, lastStatusChangeAt, monitoringEnabled, checkIntervalSeconds, snmpEnabled, snmpVersion, snmpCommunity, snmpCommunitySource, snmpPort, snmpTransport, snmpTransportSource, lastDiscoveryAt, lastSnmpPollAt, snmpv3SecurityLevel, snmpv3Username, snmpv3AuthProtocol, snmpv3PrivProtocol, snmpv3CredentialSource, mikrotikUsername, mikrotikPort, mikrotikSshPort, mikrotikUseSsl, mikrotikEnabled, mikrotikCredentialSource, deviceRole, deviceRoleSource, siteId, organizationId, insertedAt, updatedAt, site

Site

id, name, description, location, displayOrder, snmpVersion, snmpCommunity, snmpPort, snmpTransport, snmpv3SecurityLevel, snmpv3Username, snmpv3AuthProtocol, snmpv3PrivProtocol, mikrotikUsername, mikrotikPort, mikrotikSshPort, mikrotikUseSsl, mikrotikEnabled, organizationId, agentTokenId, parentSiteId, insertedAt, updatedAt

Alert

id, alertType, message, triggeredAt, acknowledgedAt, resolvedAt, emailSentAt, deviceId, acknowledgedById, gaiiaImpact, insertedAt, device, acknowledgedByEmail

Agent

id, name, enabled, isCloudPoller, allowRemoteDebug, lastSeenAt, lastIp, metadata, organizationId, insertedAt, updatedAt, deviceCount

Organization

id, name, slug, subscriptionPlan, useSites, snmpVersion, snmpCommunity, snmpPort, snmpTransport, snmpv3SecurityLevel, snmpv3Username, snmpv3AuthProtocol, snmpv3PrivProtocol, mikrotikEnabled, mikrotikUsername, mikrotikPort, mikrotikSshPort, mikrotikUseSsl, defaultAgentTokenId, insertedAt, updatedAt

Member

id, email, role, isDefault, userId, insertedAt

Integration

id, provider, enabled, syncIntervalMinutes, lastSyncedAt, lastSyncStatus, organizationId, insertedAt, updatedAt

ActivityItem

summary, detail, timestamp, severity, icon, deviceName, siteName, link, type

Utility Types

DeleteResult: success (Boolean!), message (String)
TestResult: success (Boolean!), message (String)
MetricPoint: timestamp, value, status, checkName, checkType
Interface: id, ifIndex, ifName, ifDescr, ifType, ifSpeed, ifAdminStatus, ifOperStatus, ifAlias
Invitation: id, email, role, expiresAt, acceptedAt, insertedAt
AgentWithToken: id, name, enabled, token, insertedAt

curl Examples

List devices with site info

curl -X POST https://app.towerops.net/api/graphql \
  -H "Authorization: Bearer <%= @sample_token %>" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ devices { id name ipAddress status site { id name location } } }"}'

Get active alerts

curl -X POST https://app.towerops.net/api/graphql \
  -H "Authorization: Bearer <%= @sample_token %>" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ alerts(status: \"active\") { id alertType message triggeredAt device { name ipAddress } } }"}'

Create a device

curl -X POST https://app.towerops.net/api/graphql \
  -H "Authorization: Bearer <%= @sample_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://app.towerops.net/api/graphql \
  -H "Authorization: Bearer <%= @sample_token %>" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { acknowledgeAlert(id: \"alert-uuid\") { id acknowledgedAt } }"}'

Using variables

curl -X POST https://app.towerops.net/api/graphql \
  -H "Authorization: Bearer <%= @sample_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"}
  }'