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"
""") %>