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

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

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

Response

<%= raw("""
{
  "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

<%= raw("""
curl https://towerops.net/api/v1/alerts/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \\
  -H "Authorization: Bearer #{@sample_token}"
""") %>

Acknowledge an alert

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

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

Request

<%= raw("""
curl -X POST https://towerops.net/api/v1/alerts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/acknowledge \\
  -H "Authorization: Bearer #{@sample_token}"
""") %>

Response

<%= raw("""
{
  "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": "admin@example.com",
    "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

<%= raw("""
curl -X POST https://towerops.net/api/v1/alerts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/resolve \\
  -H "Authorization: Bearer #{@sample_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

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

Response

<%= raw("""
{
  "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

<%= raw("""
curl -X POST https://towerops.net/api/v1/agents \\
  -H "Authorization: Bearer #{@sample_token}" \\
  -H "Content-Type: application/json" \\
  -d '{"name": "new-site-agent"}'
""") %>

Response (201 Created)

<%= raw("""
{
  "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

<%= raw("""
curl https://towerops.net/api/v1/agents/b2c3d4e5-f6a7-8901-bcde-f12345678901 \\
  -H "Authorization: Bearer #{@sample_token}"
""") %>

Response

<%= raw("""
{
  "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

<%= raw("""
curl -X DELETE https://towerops.net/api/v1/agents/b2c3d4e5-f6a7-8901-bcde-f12345678901 \\
  -H "Authorization: Bearer #{@sample_token}"
""") %>

Response (204 No Content)

<%= raw("""
(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

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

Response

<%= raw("""
{
  "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

<%= raw("""
curl -X PATCH https://towerops.net/api/v1/organization \\
  -H "Authorization: Bearer #{@sample_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

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

Response

<%= raw("""
{
  "data": [
    {
      "id": "user-uuid-1",
      "email": "admin@example.com",
      "role": "owner",
      "inserted_at": "2025-06-01T00:00:00Z"
    },
    {
      "id": "user-uuid-2",
      "email": "tech@example.com",
      "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

<%= raw("""
curl -X PATCH https://towerops.net/api/v1/members/user-uuid-2 \\
  -H "Authorization: Bearer #{@sample_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

<%= raw("""
curl -X DELETE https://towerops.net/api/v1/members/user-uuid-2 \\
  -H "Authorization: Bearer #{@sample_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

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

Response

<%= raw("""
{
  "data": [
    {
      "id": "inv-uuid-1",
      "email": "newuser@example.com",
      "role": "member",
      "expires_at": "2026-02-21T11:00:00Z",
      "invited_by_email": "admin@example.com",
      "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

<%= raw("""
curl -X POST https://towerops.net/api/v1/invitations \\
  -H "Authorization: Bearer #{@sample_token}" \\
  -H "Content-Type: application/json" \\
  -d '{"email": "newuser@example.com", "role": "member"}'
""") %>

Cancel an invitation

DELETE /api/v1/invitations/:id

Cancels a pending invitation.

Request

<%= raw("""
curl -X DELETE https://towerops.net/api/v1/invitations/inv-uuid-1 \\
  -H "Authorization: Bearer #{@sample_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

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

Response

<%= raw("""
{
  "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

<%= raw("""
curl -X POST https://towerops.net/api/v1/integrations \\
  -H "Authorization: Bearer #{@sample_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

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

Update an integration

PATCH /api/v1/integrations/:id

Updates an integration's settings.

Request

<%= raw("""
curl -X PATCH https://towerops.net/api/v1/integrations/intg-uuid-1 \\
  -H "Authorization: Bearer #{@sample_token}" \\
  -H "Content-Type: application/json" \\
  -d '{"integration": {"enabled": false}}'
""") %>

Delete an integration

DELETE /api/v1/integrations/:id

Permanently deletes an integration.

Request

<%= raw("""
curl -X DELETE https://towerops.net/api/v1/integrations/intg-uuid-1 \\
  -H "Authorization: Bearer #{@sample_token}"
""") %>

Test connection

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

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

Request

<%= raw("""
curl -X POST https://towerops.net/api/v1/integrations/intg-uuid-1/test \\
  -H "Authorization: Bearer #{@sample_token}"
""") %>

Response

<%= raw("""
{
  "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

<%= raw(~S"""
curl -G https://towerops.net/api/v1/checks \
  -H "Authorization: Bearer {token}" \
  -d check_type=http
""") %>

Response

<%= raw(~S"""
{
  "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

<%= raw(~S"""
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

<%= raw(~S"""
{
  "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

<%= raw(~S"""
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

<%= raw(~S"""
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

<%= raw(~S"""
curl -X DELETE https://towerops.net/api/v1/checks/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  -H "Authorization: Bearer {token}"
""") %>

Response

<%= raw(~S"""
{
  "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

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

Response

<%= raw("""
{
  "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

<%= raw("""
curl -G https://towerops.net/api/v1/devices/550e8400-e29b-41d4-a716-446655440000/metrics \\
  -H "Authorization: Bearer #{@sample_token}" \\
  -d hours=48 \\
  -d check_type=ping
""") %>

Response

<%= raw("""
{
  "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

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

Response

<%= raw("""
{
  "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

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

Response

<%= raw("""
{
  "data": [
    {
      "type": "device_created",
      "message": "Device 'Core Router' was added",
      "user_email": "admin@example.com",
      "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"
    }
  ]
}
""") %>

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.