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:

curl https://towerops.net/api/v1/sites \
  -H "Authorization: Bearer YOUR_API_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

curl -G https://towerops.net/api/v1/sites \
  -H "Authorization: Bearer {token}"

Response

{
  "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

curl https://towerops.net/api/v1/sites \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "site": {
      "name": "Main Office",
      "location": "New York, NY",
      "snmp_community": "public"
    }
  }'

Response

{
  "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

curl https://towerops.net/api/v1/sites/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer {token}"

Response

{
  "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

curl -X PATCH https://towerops.net/api/v1/sites/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "site": {
      "name": "Updated Office Name"
    }
  }'

Response

{
  "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

curl -X DELETE https://towerops.net/api/v1/sites/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer {token}"

Response

{
  "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

curl -G https://towerops.net/api/v1/devices \
  -H "Authorization: Bearer {token}"

Response

{
  "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

curl https://towerops.net/api/v1/devices \
  -H "Authorization: Bearer {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

{
  "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

curl https://towerops.net/api/v1/devices/650e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer {token}"

Response

{
  "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

curl -X PATCH https://towerops.net/api/v1/devices/650e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "device": {
      "name": "Updated Router Name",
      "monitoring_enabled": false
    }
  }'

Response

{
  "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

curl -X DELETE https://towerops.net/api/v1/devices/650e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true
}