Towerops API Reference

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

Official clients

Drive Towerops as code. The Ansible collection wraps every resource on this page with idempotent modules: codeberg.org/towerops/ansible.

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 YOUR_API_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 YOUR_API_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 YOUR_API_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 YOUR_API_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 YOUR_API_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 YOUR_API_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 YOUR_API_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 YOUR_API_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 YOUR_API_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 YOUR_API_TOKEN"

Response

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

# 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

{
  "profile": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "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": "[email protected]",
      "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

Content-Type: application/json
Content-Disposition: attachment; filename="towerops-data-{user_id}-{timestamp}.json"

Alerts

Alerts represent monitoring events triggered when a device check fails or recovers. You can list, view, acknowledge, and resolve alerts.

The alert model

id string: Unique identifier (UUID).
alert_type string: Type of alert (e.g. "ping_down", "snmp_down").
message string: Human-readable alert message.
triggered_at timestamp: When the alert was triggered.
acknowledged_at timestamp: When the alert was acknowledged (null if not acknowledged).
resolved_at timestamp: When the alert was resolved (null if still active).
device_id string: The device this alert belongs to.
device_name string: Name of the associated device.
acknowledged_by_email string: Email of the user who acknowledged this alert.
gaiia_impact string: AI-generated impact assessment (if available).

List all alerts

GET /api/v1/alerts

Returns all alerts for the authenticated organization.

Optional parameters

status string: Filter by status (e.g. "active", "acknowledged", "resolved").
device_id string: Filter alerts for a specific device.
limit integer: Maximum number of alerts to return.

Request

curl -G https://towerops.net/api/v1/alerts \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d status=active

Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "alert_type": "ping_down",
      "message": "Device is not responding to ping",
      "triggered_at": "2026-02-14T10:30:00Z",
      "acknowledged_at": null,
      "resolved_at": null,
      "device_id": "550e8400-e29b-41d4-a716-446655440000",
      "device_name": "Core Router",
      "acknowledged_by_email": null,
      "gaiia_impact": "High - affects 12 downstream devices",
      "inserted_at": "2026-02-14T10:30:00Z"
    }
  ]
}

Retrieve an alert

GET /api/v1/alerts/:id

Retrieves a single alert by its ID.

Request

curl https://towerops.net/api/v1/alerts/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Acknowledge an alert

POST /api/v1/alerts/:id/acknowledge

Marks an alert as acknowledged. The acknowledging user is recorded automatically.

Request

curl -X POST https://towerops.net/api/v1/alerts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/acknowledge \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "alert_type": "ping_down",
    "message": "Device is not responding to ping",
    "triggered_at": "2026-02-14T10:30:00Z",
    "acknowledged_at": "2026-02-14T11:00:00Z",
    "resolved_at": null,
    "device_id": "550e8400-e29b-41d4-a716-446655440000",
    "device_name": "Core Router",
    "acknowledged_by_email": "[email protected]",
    "gaiia_impact": "High - affects 12 downstream devices",
    "inserted_at": "2026-02-14T10:30:00Z"
  }
}

Resolve an alert

POST /api/v1/alerts/:id/resolve

Manually resolves an alert. Alerts may also be resolved automatically when the underlying condition clears.

Request

curl -X POST https://towerops.net/api/v1/alerts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/resolve \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Agents

Agents are lightweight monitoring agents that run on your infrastructure to collect device data. Each agent has a token used for authentication.

The agent model

id string: Unique identifier (UUID).
name string: Name of the agent.
enabled boolean: Whether the agent is enabled.
last_seen_at timestamp: When the agent last checked in.
last_ip string: Last known IP address of the agent.
metadata object: Agent metadata (version, OS, etc.).

List all agents

GET /api/v1/agents

Returns all agent tokens for the authenticated organization.

Request

curl -G https://towerops.net/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "data": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "datacenter-agent-01",
      "enabled": true,
      "last_seen_at": "2026-02-14T11:00:00Z",
      "last_ip": "10.0.1.50",
      "metadata": {"version": "1.4.2", "os": "linux"},
      "inserted_at": "2026-01-10T08:00:00Z"
    }
  ]
}

Create an agent

POST /api/v1/agents

Creates a new agent token. The raw token is returned only once in the response — store it securely.

Required parameters

name string: A descriptive name for the agent.

Request

curl -X POST https://towerops.net/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "new-site-agent"}'

Response (201 Created)

{
  "data": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "name": "new-site-agent",
    "enabled": true,
    "last_seen_at": null,
    "last_ip": null,
    "metadata": null,
    "inserted_at": "2026-02-14T11:10:00Z",
    "token": "tow_agent_abc123..."
  }
}

Retrieve an agent

GET /api/v1/agents/:id

Retrieves a single agent by ID. Includes a count of assigned devices.

Request

curl https://towerops.net/api/v1/agents/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "datacenter-agent-01",
    "enabled": true,
    "last_seen_at": "2026-02-14T11:00:00Z",
    "last_ip": "10.0.1.50",
    "metadata": {"version": "1.4.2", "os": "linux"},
    "inserted_at": "2026-01-10T08:00:00Z",
    "device_count": 24
  }
}

Delete an agent

DELETE /api/v1/agents/:id

Permanently deletes an agent token. Devices assigned to this agent will need to be reassigned.

Request

curl -X DELETE https://towerops.net/api/v1/agents/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response (204 No Content)

(empty response body)

Organization

Retrieve and update settings for the authenticated organization, including SNMP defaults, MikroTik configuration, and general preferences.

The organization model

id string: Unique identifier (UUID).
name string: Organization display name.
slug string: URL-friendly identifier.
subscription_plan string: Current subscription plan.
snmp_version string: Default SNMP version (v2c or v3).
snmp_community string: Default SNMP community string.
mikrotik_enabled boolean: Whether MikroTik API integration is enabled.

Get organization settings

GET /api/v1/organization

Returns the full settings for the authenticated organization.

Request

curl https://towerops.net/api/v1/organization \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "data": {
    "id": "org-uuid-here",
    "name": "Acme Networks",
    "slug": "acme-networks",
    "subscription_plan": "pro",
    "use_sites": true,
    "snmp_version": "v2c",
    "snmp_community": "public",
    "snmp_port": 161,
    "snmp_transport": "udp",
    "snmpv3_security_level": null,
    "snmpv3_username": null,
    "snmpv3_auth_protocol": null,
    "snmpv3_priv_protocol": null,
    "mikrotik_enabled": false,
    "mikrotik_username": null,
    "mikrotik_port": null,
    "mikrotik_ssh_port": null,
    "mikrotik_use_ssl": false,
    "default_agent_token_id": null,
    "inserted_at": "2025-06-01T00:00:00Z",
    "updated_at": "2026-02-14T10:00:00Z"
  }
}

Update organization settings

PATCH /api/v1/organization

Updates organization settings. Only the provided fields are changed.

Parameters (all optional)

organization[name] string: Organization display name.
organization[snmp_community] string: Default SNMP community string.

Request

curl -X PATCH https://towerops.net/api/v1/organization \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"organization": {"name": "Acme Networks LLC", "snmp_community": "private"}}'

Members

Manage the users who belong to your organization. You can list members, change roles, and remove members.

The member model

id string: User ID of the member.
email string: Email address of the member.
role string: Member's role (e.g. "owner", "admin", "member").

List all members

GET /api/v1/members

Returns all members of the authenticated organization.

Request

curl -G https://towerops.net/api/v1/members \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "data": [
    {
      "id": "user-uuid-1",
      "email": "[email protected]",
      "role": "owner",
      "inserted_at": "2025-06-01T00:00:00Z"
    },
    {
      "id": "user-uuid-2",
      "email": "[email protected]",
      "role": "admin",
      "inserted_at": "2025-08-15T00:00:00Z"
    }
  ]
}

Change member role

PATCH /api/v1/members/:user_id

Updates a member's role. Cannot change the owner's role.

Required parameters

role string: New role for the member (e.g. "admin", "member").

Request

curl -X PATCH https://towerops.net/api/v1/members/user-uuid-2 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "member"}'

Remove a member

DELETE /api/v1/members/:user_id

Removes a member from the organization. The organization owner cannot be removed.

Request

curl -X DELETE https://towerops.net/api/v1/members/user-uuid-2 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Invitations

Invite new users to your organization. Invitations expire after 7 days.

The invitation model

id string: Unique identifier (UUID).
email string: Email address of the invited user.
role string: Role the user will receive upon accepting.
expires_at timestamp: When the invitation expires.
invited_by_email string: Email of the user who sent the invitation.

List pending invitations

GET /api/v1/invitations

Returns all pending invitations for the organization.

Request

curl -G https://towerops.net/api/v1/invitations \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "data": [
    {
      "id": "inv-uuid-1",
      "email": "[email protected]",
      "role": "member",
      "expires_at": "2026-02-21T11:00:00Z",
      "invited_by_email": "[email protected]",
      "inserted_at": "2026-02-14T11:00:00Z"
    }
  ]
}

Create an invitation

POST /api/v1/invitations

Sends an invitation to join the organization.

Required parameters

email string: Email address to invite.
role string: Role to assign (e.g. "admin", "member").

Request

curl -X POST https://towerops.net/api/v1/invitations \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "role": "member"}'

Cancel an invitation

DELETE /api/v1/invitations/:id

Cancels a pending invitation.

Request

curl -X DELETE https://towerops.net/api/v1/invitations/inv-uuid-1 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Integrations

Manage third-party integrations for your organization, such as notification providers and external monitoring systems.

The integration model

id string: Unique identifier (UUID).
provider string: Integration provider name (e.g. "slack", "pagerduty", "email").
enabled boolean: Whether the integration is active.
sync_interval_minutes integer: How often the integration syncs (in minutes).
last_synced_at timestamp: When the integration last synced.
last_sync_status string: Status of the last sync ("success", "error", etc.).

List all integrations

GET /api/v1/integrations

Returns all integrations for the organization.

Request

curl -G https://towerops.net/api/v1/integrations \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "data": [
    {
      "id": "intg-uuid-1",
      "provider": "slack",
      "enabled": true,
      "sync_interval_minutes": 5,
      "last_synced_at": "2026-02-14T11:00:00Z",
      "last_sync_status": "success",
      "inserted_at": "2025-12-01T00:00:00Z",
      "updated_at": "2026-02-14T11:00:00Z"
    }
  ]
}

Create an integration

POST /api/v1/integrations

Creates a new integration.

Required parameters

integration[provider] string: Provider name (e.g. "slack", "pagerduty").

Optional parameters

integration[enabled] boolean: Whether to enable the integration immediately (default: true).
integration[sync_interval_minutes] integer: Sync interval in minutes.

Request

curl -X POST https://towerops.net/api/v1/integrations \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"integration": {"provider": "slack", "enabled": true, "sync_interval_minutes": 5}}'

Retrieve an integration

GET /api/v1/integrations/:id

Retrieves a single integration by ID.

Request

curl https://towerops.net/api/v1/integrations/intg-uuid-1 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Update an integration

PATCH /api/v1/integrations/:id

Updates an integration's settings.

Request

curl -X PATCH https://towerops.net/api/v1/integrations/intg-uuid-1 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"integration": {"enabled": false}}'

Delete an integration

DELETE /api/v1/integrations/:id

Permanently deletes an integration.

Request

curl -X DELETE https://towerops.net/api/v1/integrations/intg-uuid-1 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Test connection

POST /api/v1/integrations/:id/test

Tests the connection for an integration to verify it's properly configured.

Request

curl -X POST https://towerops.net/api/v1/integrations/intg-uuid-1/test \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "data": {
    "status": "ok",
    "provider": "slack"
  }
}

Checks

Service checks monitor the availability and responsiveness of network services. Supported check types: HTTP, TCP, DNS, and ping. SNMP checks are managed internally and are not exposed via this API.

The check model

id string: Unique identifier for the check (UUID).
name string: The name of the check.
check_type string: The type of check: http, tcp, dns, or ping.
enabled boolean: Whether the check is enabled and scheduled to run.
config object: Type-specific configuration. HTTP: url, method, expected_status, verify_ssl, follow_redirects, regex. TCP: host, port, send, expect. DNS: hostname, record_type, server, expected. Ping: host, count.
interval_seconds integer: How often the check runs, in seconds. Default: 60.
current_state integer: Current check state: 0=OK, 1=WARNING, 2=CRITICAL, 3=UNKNOWN.
current_state_type string: Current state type: soft or hard.

List all checks

GET /api/v1/checks

Lists all service checks for the authenticated organization. Only returns HTTP, TCP, DNS, and ping checks.

Optional query parameters

check_type string: Filter by check type: http, tcp, dns, or ping.
device_id string: Filter checks by device UUID.

Request

curl -G https://towerops.net/api/v1/checks \
  -H "Authorization: Bearer {token}" \
  -d check_type=http

Response

{
  "checks": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Web Health Check",
      "check_type": "http",
      "enabled": true,
      "config": {"url": "https://example.com/health", "expected_status": 200},
      "interval_seconds": 60,
      "current_state": 0,
      "current_state_type": "hard",
      "last_check_at": "2026-03-16T12:00:00Z",
      "inserted_at": "2026-03-15T10:00:00Z"
    }
  ]
}

Create a check

POST /api/v1/checks

Creates a new service check for the authenticated organization. The check is automatically scheduled if enabled.

Required parameters

name string: The name of the check.
check_type string: One of: http, tcp, dns, ping.
config object: Type-specific configuration object. See check model for available fields.

Optional parameters

enabled boolean: Whether the check is enabled. Default: true.
device_id string: Associate the check with a device.
interval_seconds integer: How often the check runs. Default: 60.

Request

curl https://towerops.net/api/v1/checks \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"check": {"name": "Web Health", "check_type": "http", "config": {"url": "https://example.com/health", "expected_status": 200}}}'

Response 201 Created

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "Web Health",
  "check_type": "http",
  "enabled": true,
  "config": {"url": "https://example.com/health", "expected_status": 200},
  "interval_seconds": 60,
  "timeout_ms": 5000,
  "current_state": null,
  "inserted_at": "2026-03-16T10:00:00Z"
}

Retrieve a check

GET /api/v1/checks/:id

Retrieves a single check by its UUID.

Request

curl https://towerops.net/api/v1/checks/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  -H "Authorization: Bearer {token}"

Update a check

PATCH /api/v1/checks/:id

Updates an existing check. Only the provided fields will be updated.

Request

curl -X PATCH https://towerops.net/api/v1/checks/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"check": {"name": "Updated Name", "interval_seconds": 120}}'

Delete a check

DELETE /api/v1/checks/:id

Deletes a check and cancels any scheduled executions.

Request

curl -X DELETE https://towerops.net/api/v1/checks/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true
}

Check Results & Metrics

Access monitoring check results, historical metrics, and SNMP interface data for your devices.

List device checks

GET /api/v1/devices/:device_id/checks

Returns all monitoring checks configured for a device, including the latest result for each check.

Request

curl -G https://towerops.net/api/v1/devices/550e8400-e29b-41d4-a716-446655440000/checks \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "data": [
    {
      "id": "check-uuid-1",
      "name": "ICMP Ping",
      "check_type": "ping",
      "enabled": true,
      "interval_seconds": 60,
      "latest_status": "ok",
      "latest_value": 12.5,
      "latest_checked_at": "2026-02-14T11:10:00Z"
    }
  ]
}

Get device metrics

GET /api/v1/devices/:device_id/metrics

Returns historical check results for a device, useful for graphing and trend analysis.

Optional parameters

hours integer: Number of hours of history to return (default: 24).
check_type string: Filter by check type (e.g. "ping", "snmp").

Request

curl -G https://towerops.net/api/v1/devices/550e8400-e29b-41d4-a716-446655440000/metrics \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d hours=48 \
  -d check_type=ping

Response

{
  "data": [
    {
      "check_id": "check-uuid-1",
      "check_name": "ICMP Ping",
      "check_type": "ping",
      "data": [
        {"timestamp": "2026-02-14T10:00:00Z", "value": 11.2, "status": "ok"},
        {"timestamp": "2026-02-14T10:01:00Z", "value": 13.8, "status": "ok"},
        {"timestamp": "2026-02-14T10:02:00Z", "value": null, "status": "timeout"}
      ]
    }
  ]
}

List device interfaces

GET /api/v1/devices/:device_id/interfaces

Returns SNMP-discovered network interfaces for a device.

Request

curl -G https://towerops.net/api/v1/devices/550e8400-e29b-41d4-a716-446655440000/interfaces \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "data": [
    {
      "id": "iface-uuid-1",
      "if_index": 1,
      "if_name": "GigabitEthernet0/0",
      "if_descr": "GigabitEthernet0/0",
      "if_alias": "Uplink to ISP",
      "if_speed": 1000000000,
      "if_admin_status": "up",
      "if_oper_status": "up",
      "monitored": true
    }
  ]
}

Activity Feed

View a chronological feed of actions and events across your organization.

List organization activity

GET /api/v1/activity

Returns recent activity events for the organization.

Optional parameters

limit integer: Maximum number of events to return (default: 50).
types string: Comma-separated list of event types to filter by.

Request

curl -G https://towerops.net/api/v1/activity \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d limit=20

Response

{
  "data": [
    {
      "type": "device_created",
      "message": "Device 'Core Router' was added",
      "user_email": "[email protected]",
      "inserted_at": "2026-02-14T10:30:00Z"
    },
    {
      "type": "alert_triggered",
      "message": "Alert triggered: ping_down on Core Router",
      "user_email": null,
      "inserted_at": "2026-02-14T10:35:00Z"
    }
  ]
}

RF Coverages

RF coverage predictions model where each radio actually reaches. Compute is async — a created or recomputed coverage starts in queued and progresses through computing to ready or failed. The status field is present on every response so polling-based clients (Terraform, the Ansible collection, scripts) can wait for a healthy resource. Outputs include a coloured PNG heatmap, a Float32 GeoTIFF raster, and a downloadable KMZ bundle for Google Earth.

List all coverages

GET /api/v1/coverages. Returns every coverage in the authenticated organization, regardless of status.

curl -G https://towerops.net/api/v1/coverages \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Create a coverage

POST /api/v1/coverages. Creates a new coverage and immediately enqueues compute. Required: name, site_id, antenna_slug, frequency_mhz, tx_power_dbm, height_agl_m, azimuth_deg, radius_m. Optional fields tune cell size, downtilt, foliage, receiver height, and threshold.

curl -X POST https://towerops.net/api/v1/coverages \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "coverage": {
      "name": "North sector 5 GHz",
      "site_id": "550e8400-e29b-41d4-a716-446655440000",
      "antenna_slug": "rf-elements-twistport-symmetrical-horn-30",
      "frequency_mhz": 5800,
      "tx_power_dbm": 22.0,
      "height_agl_m": 30,
      "azimuth_deg": 0,
      "downtilt_deg": 2,
      "radius_m": 6000,
      "cell_size_m": 10
    }
  }'

Retrieve a coverage

GET /api/v1/coverages/:id. Returns one coverage including its bbox, status, progress percentage, and (when ready) the png_path + raster_path outputs.

curl https://towerops.net/api/v1/coverages/COV_ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Update a coverage

PATCH /api/v1/coverages/:id. Mutates editable fields (name, antenna parameters, radius, cell size, etc.). Does not auto-recompute — call the recompute endpoint when you want fresh outputs.

curl -X PATCH https://towerops.net/api/v1/coverages/COV_ID \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"coverage": {"tx_power_dbm": 25.0}}'

Recompute a coverage

POST /api/v1/coverages/:id/recompute. Re-queues the compute pipeline without changing any parameters. Returns 409 Conflict if the coverage is already computing. Useful after a parameter update or after the antenna catalog is refreshed.

curl -X POST https://towerops.net/api/v1/coverages/COV_ID/recompute \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Download as KMZ

GET /api/v1/coverages/:id/kmz. Returns a Google Earth-compatible KMZ bundle (KML + PNG). Returns 409 Conflict if the coverage is not yet ready.

curl -OJ https://towerops.net/api/v1/coverages/COV_ID/kmz \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Delete a coverage

DELETE /api/v1/coverages/:id. Removes the coverage and any cached outputs. Returns 204 No Content on success.

curl -X DELETE https://towerops.net/api/v1/coverages/COV_ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Maintenance Windows

Maintenance windows tell Towerops to suppress alerts for a site or device during planned work. Windows can be one-off or recurring (iCal RRULE).

List maintenance windows

GET /api/v1/maintenance_windows. Optional filter query param accepts active, upcoming, or past.

curl -G https://towerops.net/api/v1/maintenance_windows \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d filter=active

Create a maintenance window

POST /api/v1/maintenance_windows. Required: name, starts_at, ends_at. Scope to a site or a specific device. Set recurring: true with a recurrence_rule (RRULE) to repeat.

curl -X POST https://towerops.net/api/v1/maintenance_windows \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "maintenance_window": {
      "name": "Quarterly firmware roll",
      "starts_at": "2026-06-01T05:00:00Z",
      "ends_at":   "2026-06-01T09:00:00Z",
      "site_id":   "SITE_UUID",
      "suppress_alerts": true
    }
  }'

Get / update / delete

Standard CRUD on /api/v1/maintenance_windows/:id. GET returns the resource; PATCH updates fields with the same body shape as create; DELETE returns a JSON success body.

curl -X DELETE https://towerops.net/api/v1/maintenance_windows/WINDOW_ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

On-Call Schedules

Schedules drive who gets paged when an alert fires. A schedule contains one or more layers (rotations); each layer has ordered members. Ad-hoc overrides let you swap the on-call user for a fixed time window without changing the rotation.

Schedule CRUD

GET /api/v1/schedules, POST, GET /:id, PATCH /:id, DELETE /:id. Required on create: name, timezone. Showing one schedule returns its layers + overrides nested.

curl -X POST https://towerops.net/api/v1/schedules \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": {
      "name": "Primary on-call",
      "description": "Weekly rotation",
      "timezone": "America/Chicago"
    }
  }'

Who is on call?

GET /api/v1/schedules/:id/on_call. Returns the user currently on call (taking layers and overrides into account), or null if nobody is.

curl https://towerops.net/api/v1/schedules/SCHED_ID/on_call \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Layers and members

POST /api/v1/schedules/:id/layers, PATCH /api/v1/schedules/:id/layers/:layer_id, DELETE the same. A layer requires name, position, rotation_type (weekly/daily/custom), rotation_interval, handoff_time, and start_date.

Add and remove members with POST /:id/layers/:layer_id/members (body: user_id, position) and DELETE /:id/layers/:layer_id/members/:member_id.

curl -X POST https://towerops.net/api/v1/schedules/SCHED_ID/layers \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "layer": {
      "name": "Primary",
      "position": 0,
      "rotation_type": "weekly",
      "rotation_interval": 1,
      "handoff_time": "09:00:00",
      "start_date": "2026-06-01T00:00:00Z"
    }
  }'

Overrides

POST /api/v1/schedules/:id/overrides creates a one-off cover ("Bob is on for Alice from Friday 17:00 to Monday 09:00"). Required: user_id, start_time, end_time. Remove with DELETE /:id/overrides/:override_id.

curl -X POST https://towerops.net/api/v1/schedules/SCHED_ID/overrides \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "override": {
      "user_id": "USER_UUID",
      "start_time": "2026-06-07T17:00:00Z",
      "end_time":   "2026-06-09T09:00:00Z"
    }
  }'

Escalation Policies

Escalation policies are an ordered list of rules; each rule fires its targets after a delay if the previous rule's targets haven't acknowledged the alert. Targets can reference users, schedules, or arbitrary webhooks.

Policy CRUD

Standard REST CRUD under /api/v1/escalation_policies. GET /:id returns the policy with its rules and targets nested. Required on create: name. Optional: description, repeat_count, repeat_interval_minutes.

curl -X POST https://towerops.net/api/v1/escalation_policies \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "escalation_policy": {
      "name": "Critical alerts",
      "description": "Page primary, then secondary, then manager",
      "repeat_count": 3,
      "repeat_interval_minutes": 15
    }
  }'

Rules

POST /api/v1/escalation_policies/:id/rules appends a rule. PATCH /api/v1/escalation_policies/:id/rules/:rule_id updates one. DELETE removes one. Required on create: position, delay_minutes.

curl -X POST https://towerops.net/api/v1/escalation_policies/POLICY_ID/rules \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rule": {"position": 0, "delay_minutes": 5}
  }'

Targets

Each rule has one or more targets: POST /api/v1/escalation_policies/:id/rules/:rule_id/targets creates one, DELETE /api/v1/escalation_policies/:id/rules/:rule_id/targets/:target_id removes it. A target body specifies target_type (user, schedule, or webhook) plus the corresponding identifier or URL.

curl -X POST https://towerops.net/api/v1/escalation_policies/POLICY_ID/rules/RULE_ID/targets \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target": {"target_type": "schedule", "schedule_id": "SCHED_UUID"}
  }'

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

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

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

# 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 [email protected].