Towerops API Reference

Use the Towerops API to manage your network monitoring infrastructure programmatically. Create and monitor sites, devices, and alerts.

Authentication

All API requests require authentication using an API token. Include your token in the Authorization header:

<%= raw("""
curl https://towerops.net/api/v1/sites \\
  -H "Authorization: Bearer #{@sample_token}"
""") %>

API tokens are created and managed in your organization settings. Each token is scoped to a single organization.

Errors

The API uses conventional HTTP response codes to indicate success or failure:

Code	Description
200	Success
201	Created successfully
400	Bad request - missing or invalid parameters
401	Unauthorized - invalid or missing API token
403	Forbidden - you don't have access to this resource
404	Not found - resource doesn't exist
422	Unprocessable entity - validation errors

Sites

Sites represent physical locations where your network devices are deployed. Each site can have multiple devices and may have default SNMP configuration.

The site model

id string: Unique identifier for the site (UUID).
name string: The name of the site.
location string: Physical location or address of the site.
snmp_community string: Default SNMP community string for devices at this site (optional).
inserted_at timestamp: Timestamp when the site was created.

List all sites

GET /api/v1/sites

Lists all sites for the authenticated organization.

Request

<%= raw("""
curl -G https://towerops.net/api/v1/sites \\
  -H "Authorization: Bearer #{@sample_token}"
""") %>

Response

<%= raw("""
{
  "sites": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Main Office",
      "location": "New York, NY",
      "snmp_community": "public",
      "inserted_at": "2026-01-15T19:44:25Z"
    }
  ]
}
""") %>

Create a site

POST /api/v1/sites

Creates a new site for the authenticated organization.

Required parameters

name string: The name of the site.
location string: Physical location of the site.

Optional parameters

snmp_community string: Default SNMP community string for devices at this site.

Request

<%= raw("""
curl https://towerops.net/api/v1/sites \
  -H "Authorization: Bearer #{@sample_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "site": {
      "name": "Main Office",
      "location": "New York, NY",
      "snmp_community": "public"
    }
  }'
""") %>

Response

<%= raw("""
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Main Office",
  "location": "New York, NY",
  "snmp_community": "public",
  "inserted_at": "2026-01-15T19:44:25Z"
}
""") %>

Retrieve a site

GET /api/v1/sites/:id

Retrieves a single site by ID.

Request

<%= raw("""
curl https://towerops.net/api/v1/sites/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer #{@sample_token}"
""") %>

Response

<%= raw("""
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Main Office",
  "location": "New York, NY",
  "snmp_community": "public",
  "inserted_at": "2026-01-15T19:44:25Z"
}
""") %>

Update a site

PATCH /api/v1/sites/:id

Updates an existing site. Only provided fields will be updated.

Request

<%= raw("""
curl -X PATCH https://towerops.net/api/v1/sites/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer #{@sample_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "site": {
      "name": "Updated Office Name"
    }
  }'
""") %>

Response

<%= raw("""
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Updated Office Name",
  "location": "New York, NY",
  "snmp_community": "public",
  "inserted_at": "2026-01-15T19:44:25Z"
}
""") %>

Delete a site

DELETE /api/v1/sites/:id

Deletes a site. Note: This will also delete all devices associated with the site.

Request

<%= raw("""
curl -X DELETE https://towerops.net/api/v1/sites/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer #{@sample_token}"
""") %>

Response

<%= raw("""
{
  "success": true
}
""") %>

Devices

Devices are network equipment monitored by Towerops. Each device belongs to a site and can be monitored via ICMP ping and SNMP.

The device model

id string: Unique identifier for the device (UUID).
name string: The name of the device.
ip_address string: IP address of the device.
site_id string: ID of the site this device belongs to.
description string: Optional description of the device.
monitoring_enabled boolean: Whether monitoring is enabled for this device.
check_interval_seconds integer: How often to poll this device (in seconds).
snmp_enabled boolean: Whether SNMP monitoring is enabled.
snmp_version string: SNMP version to use (e.g., "2c").
snmp_port integer: SNMP port (default: 161).
inserted_at timestamp: Timestamp when the device was created.

List all devices

GET /api/v1/devices

Lists all devices for the authenticated organization.

Optional parameters

site_id string: Filter devices by site ID.

Request

<%= raw("""
curl -G https://towerops.net/api/v1/devices \
  -H "Authorization: Bearer #{@sample_token}"
""") %>

Response

<%= raw("""
{
  "devices": [
    {
      "id": "650e8400-e29b-41d4-a716-446655440001",
      "name": "Core Router",
      "ip_address": "192.168.1.1",
      "site_id": "550e8400-e29b-41d4-a716-446655440000",
      "monitoring_enabled": true,
      "snmp_enabled": true,
      "inserted_at": "2026-01-15T19:44:25Z"
    }
  ]
}
""") %>

Create a device

POST /api/v1/devices

Creates a new device.

Required parameters

site_id string: ID of the site this device belongs to.
name string: The name of the device.
ip_address string: IP address of the device.

Optional parameters

description string: Description of the device.
monitoring_enabled boolean: Enable monitoring (default: true).
snmp_enabled boolean: Enable SNMP monitoring (default: true).
snmp_version string: SNMP version (default: "2c").
snmp_community string: SNMP community string (inherits from site/org if not set).
snmp_port integer: SNMP port (default: 161).

Request

<%= raw("""
curl https://towerops.net/api/v1/devices \
  -H "Authorization: Bearer #{@sample_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "device": {
      "site_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Core Router",
      "ip_address": "192.168.1.1",
      "description": "Main router",
      "snmp_community": "public"
    }
  }'
""") %>

Response

<%= raw("""
{
  "id": "650e8400-e29b-41d4-a716-446655440001",
  "name": "Core Router",
  "ip_address": "192.168.1.1",
  "site_id": "550e8400-e29b-41d4-a716-446655440000",
  "monitoring_enabled": true,
  "snmp_enabled": true,
  "inserted_at": "2026-01-15T19:44:25Z"
}
""") %>

Retrieve a device

GET /api/v1/devices/:id

Retrieves a single device by ID, including all configuration details.

Request

<%= raw("""
curl https://towerops.net/api/v1/devices/650e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer #{@sample_token}"
""") %>

Response

<%= raw("""
{
  "id": "650e8400-e29b-41d4-a716-446655440001",
  "name": "Core Router",
  "ip_address": "192.168.1.1",
  "site_id": "550e8400-e29b-41d4-a716-446655440000",
  "description": "Main router",
  "monitoring_enabled": true,
  "check_interval_seconds": 300,
  "snmp_enabled": true,
  "snmp_version": "2c",
  "snmp_port": 161,
  "inserted_at": "2026-01-15T19:44:25Z"
}
""") %>

Update a device

PATCH /api/v1/devices/:id

Updates an existing device. Only provided fields will be updated.

Request

<%= raw("""
curl -X PATCH https://towerops.net/api/v1/devices/650e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer #{@sample_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "device": {
      "name": "Updated Router Name",
      "monitoring_enabled": false
    }
  }'
""") %>

Response

<%= raw("""
{
  "id": "650e8400-e29b-41d4-a716-446655440001",
  "name": "Updated Router Name",
  "ip_address": "192.168.1.1",
  "site_id": "550e8400-e29b-41d4-a716-446655440000",
  "description": "Main router",
  "monitoring_enabled": false,
  "check_interval_seconds": 300,
  "snmp_enabled": true,
  "snmp_version": "2c",
  "snmp_port": 161,
  "inserted_at": "2026-01-15T19:44:25Z"
}
""") %>

Delete a device

DELETE /api/v1/devices/:id

Deletes a device. Note: This will also delete all monitoring data associated with the device.

Request

<%= raw("""
curl -X DELETE https://towerops.net/api/v1/devices/650e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer #{@sample_token}"
""") %>

Response

<%= raw("""
{
  "success": true
}
""") %>

Account Data (GDPR)

GDPR Right to Access endpoint that allows users to download all their personal data in JSON format. This endpoint complies with Article 15 of GDPR.

Authentication Difference

This endpoint requires browser session authentication, not API tokens. Users must be logged into their Towerops account via the web interface to access this endpoint.

Export all account data

GET /api/v1/account/data

Downloads all personal data associated with the authenticated user account as a JSON file. This includes:

Profile information (email, name, timezone)
Organizations and membership roles
Devices across all organizations
Recent alerts (last 90 days)
Audit logs (up to 1,000 most recent)

Privacy Note: Sensitive data like SNMP community strings are redacted from the export for security.

Authentication

Requires active browser session with CSRF token. Cannot be accessed via API tokens.

Request (Browser)

<%= raw(~S"""
# This endpoint requires browser authentication
# Access via logged-in browser session:
GET https://towerops.net/api/v1/account/data

# Or via curl with session cookie:
curl https://towerops.net/api/v1/account/data \
  -H "Cookie: _towerops_key=YOUR_SESSION_COOKIE"
""") %>

Response

<%= raw(~S"""
{
  "profile": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "timezone": "America/New_York",
    "is_superuser": false,
    "confirmed_at": "2026-01-15T10:30:00Z",
    "inserted_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-20T14:22:00Z"
  },
  "credentials": [
    {
      "id": "750e8400-e29b-41d4-a716-446655440002",
      "label": "MacBook Pro Touch ID",
      "public_key_spki": "MFkwEwYHKoZIzj0CAQYIKoZI...",
      "last_used_at": "2026-01-28T12:15:00Z",
      "inserted_at": "2026-01-15T10:35:00Z"
    }
  ],
  "organizations": [
    {
      "id": "850e8400-e29b-41d4-a716-446655440003",
      "name": "Acme Networks",
      "slug": "acme-networks",
      "role": "owner",
      "inserted_at": "2026-01-15T10:32:00Z",
      "updated_at": "2026-01-15T10:32:00Z"
    }
  ],
  "devices": [
    {
      "id": "650e8400-e29b-41d4-a716-446655440001",
      "name": "Core Router",
      "ip_address": "192.168.1.1",
      "snmp_community": "[REDACTED]",
      "monitoring_enabled": true,
      "snmp_enabled": true,
      "status": "up",
      "organization": {
        "id": "850e8400-e29b-41d4-a716-446655440003",
        "name": "Acme Networks"
      },
      "site": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Main Office"
      },
      "inserted_at": "2026-01-16T09:00:00Z",
      "updated_at": "2026-01-28T08:30:00Z"
    }
  ],
  "alerts": [
    {
      "id": "950e8400-e29b-41d4-a716-446655440004",
      "alert_type": "equipment_down",
      "severity": "critical",
      "message": "Device is not responding to ping",
      "triggered_at": "2026-01-27T15:45:00Z",
      "resolved_at": "2026-01-27T16:10:00Z",
      "acknowledged_at": null,
      "device": {
        "id": "650e8400-e29b-41d4-a716-446655440001",
        "name": "Core Router"
      },
      "inserted_at": "2026-01-27T15:45:00Z"
    }
  ],
  "audit_logs": [
    {
      "id": "150e8400-e29b-41d4-a716-446655440005",
      "action": "user.login",
      "actor_email": "user@example.com",
      "target_user_id": "550e8400-e29b-41d4-a716-446655440000",
      "metadata": {
        "ip_address": "203.0.113.42",
        "user_agent": "Mozilla/5.0..."
      },
      "inserted_at": "2026-01-28T08:00:00Z"
    }
  ],
  "export_info": {
    "exported_at": "2026-01-28T19:50:00Z",
    "format": "JSON",
    "gdpr_article": "Article 15 - Right to Access"
  }
}
""") %>

Response Headers

<%= raw(~S"""
Content-Type: application/json
Content-Disposition: attachment; filename="towerops-data-{user_id}-{timestamp}.json"
""") %>

Terraform Provider

Manage your Towerops infrastructure as code using our official Terraform provider. Automate site and device provisioning, version control your network configuration, and integrate Towerops into your existing infrastructure workflows.

Infrastructure as Code

The Terraform provider uses the same REST API documented above. All resource operations require API token authentication (not browser sessions).

What is Terraform?

Terraform is an infrastructure as code tool that lets you define both cloud and on-premise resources in human-readable configuration files that you can version, reuse, and share. With the Towerops Terraform provider, you can:

Define sites and devices in declarative configuration files
Version control your network monitoring infrastructure
Automate device provisioning and updates
Integrate with CI/CD pipelines for automated deployments
Ensure consistent configuration across environments
Track infrastructure changes with git history

Getting Started

Installation

The provider is available on the Terraform Registry. Terraform will automatically download it when you run terraform init.

Requirements

Terraform >= 1.0
Towerops API token (create in Organization Settings)

Configuration

<%= raw(~S"""
terraform {
  required_providers {
    towerops = {
      source  = "towerops-app/towerops"
      version = "~> 0.1"
    }
  }
}

variable "towerops_api_token" {
  type      = string
  sensitive = true
}

provider "towerops" {
  token   = var.towerops_api_token
  api_url = "https://towerops.net"
}
""") %>

Example Usage

This example creates a site and two devices. Terraform will automatically manage the lifecycle of these resources, creating, updating, or deleting them as needed to match your configuration.

Key Features

Automatic dependency management (devices depend on sites)
State tracking to detect configuration drift
Plan preview before making changes
Rollback support via version control

main.tf

<%= raw(~S"""
resource "towerops_site" "main_office" {
  name     = "Main Office"
  location = "New York, NY"
}

resource "towerops_device" "core_router" {
  site_id      = towerops_site.main_office.id
  name         = "Core Router"
  ip_address   = "192.168.1.1"
  description  = "Primary gateway"
  snmp_enabled = true
  snmp_version = "2c"
}

resource "towerops_device" "backup_router" {
  site_id      = towerops_site.main_office.id
  name         = "Backup Router"
  ip_address   = "192.168.1.2"
  description  = "Failover gateway"
  snmp_enabled = true
}
""") %>

Commands

<%= raw(~S"""
# Initialize and download provider
terraform init

# Preview changes
terraform plan

# Apply configuration
terraform apply

# Destroy all resources
terraform destroy
""") %>

Available Resources

towerops_site: Manages a physical site/location. Supports name, location, and SNMP community string configuration.; View documentation →
towerops_device: Manages network equipment at a site. Supports IP address, SNMP configuration, monitoring settings, and more.; View documentation →

Full Documentation

Provider Documentation

Complete reference for all resources, data sources, and provider configuration options.

GitHub Repository

Source code, examples, and issue tracking for the Terraform provider.

Need Help?

For questions about the Terraform provider, please open an issue on GitHub or contact us at hi@towerops.net.