<.link navigate={~p"/"} class="text-2xl font-bold text-zinc-900 dark:text-white"> Towerops API

# 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
    }