TowerOps API Reference

Lists sites for the authenticated organization, one page at a time. With no pagination parameters the first page of 100 is returned, the list is never unbounded, and `meta` is always present. Responses also carry `X-Page`, `X-Per-Page`, `X-Total-Count` and `X-Total-Pages` headers.

Requires scope sites:read

Responses

200 application/json

Sites

400 application/json

The `cursor` parameter did not decode

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -G https://staging.towerops.net/api/v1/sites \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-urlencode "cursor=VALUE" \
  --data-urlencode "page=1" \
  --data-urlencode "per_page=50"

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "inserted_at": "2026-01-15T19:44:25Z",
      "location": "New York, NY",
      "name": "Main Office",
      "snmp_community_set": true,
      "snmp_port": 161,
      "snmp_version": "2c"
    }
  ],
  "meta": {
    "next_cursor": null,
    "page": 1,
    "per_page": 50,
    "total_count": 1,
    "total_pages": 1
  }
}

Creates a site in the authenticated organization.

Requires scope sites:write

Responses

201 application/json

The created site

400 application/json

The `site` parameter is missing

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X POST https://staging.towerops.net/api/v1/sites \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "site": {
    "address": "string",
    "agent_token_id": "550e8400-e29b-41d4-a716-446655440000",
    "description": "string",
    "display_order": 0,
    "latitude": 0.0,
    "location": "string",
    "longitude": 0.0,
    "name": "string",
    "parent_site_id": "550e8400-e29b-41d4-a716-446655440000",
    "snmp_community": "string",
    "snmp_port": 0,
    "snmp_transport": "udp",
    "snmp_version": "string"
  }
}'

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "location": "New York, NY",
    "name": "Main Office",
    "snmp_community_set": true,
    "snmp_port": 161,
    "snmp_version": "2c"
  }
}

Gets one site by ID.

Requires scope sites:read

Responses

200 application/json

The site

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No site with that ID in this organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl https://staging.towerops.net/api/v1/sites/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "location": "New York, NY",
    "name": "Main Office",
    "snmp_community_set": true,
    "snmp_port": 161,
    "snmp_version": "2c"
  }
}

Updates the given attributes of a site. Omitted attributes are left alone.

Requires scope sites:write

Responses

200 application/json

The updated site

400 application/json

The `site` parameter is missing

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No site with that ID in this organization

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X PATCH https://staging.towerops.net/api/v1/sites/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "site": {
    "address": "string",
    "agent_token_id": "550e8400-e29b-41d4-a716-446655440000",
    "description": "string",
    "display_order": 0,
    "latitude": 0.0,
    "location": "string",
    "longitude": 0.0,
    "name": "string",
    "parent_site_id": "550e8400-e29b-41d4-a716-446655440000",
    "snmp_community": "string",
    "snmp_port": 0,
    "snmp_transport": "udp",
    "snmp_version": "string"
  }
}'

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "location": "New York, NY",
    "name": "Main Office",
    "snmp_community_set": true,
    "snmp_port": 161,
    "snmp_version": "2c"
  }
}

Deletes a site, every site under it, the devices at all of them, and the alerts raised against them.

Requires scope sites:write

Responses

200 application/json

The site was deleted

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No site with that ID in this organization

422 application/json

The site could not be deleted

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X DELETE https://staging.towerops.net/api/v1/sites/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "deleted": true
  }
}

Lists devices for the authenticated organization, one page at a time. With no pagination parameters the first page of 100 is returned, the list is never unbounded, and `meta` is always present. `coverage_below` narrows the result to active, monitored devices below that seven-day percentage. The device list is returned under `data` and the next-page cursor under `meta.next_cursor`. A `page` past the last one returns an empty `data`, so paging until the list is empty terminates. `updated_since` (ISO 8601 with an offset) limits the list to devices whose `updated_at` is at or after that instant, and the window closes at the request's own `as_of`, rows and `meta.total_count` alike, so `meta.window.until` equals `as_of`. A write committed after `as_of` can carry an earlier `updated_at`, so resume a few minutes before `as_of`; the overlap is idempotent. `meta.window` echoes the exact bounds the query applied. An unparseable `updated_since` is rejected with `bad_request`.

Requires scope devices:read

Responses

200 application/json

Devices

400 application/json

The `cursor` parameter did not decode

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -G https://staging.towerops.net/api/v1/devices \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-urlencode "coverage_below=90" \
  --data-urlencode "cursor=VALUE" \
  --data-urlencode "page=1" \
  --data-urlencode "per_page=50" \
  --data-urlencode "site_id=VALUE" \
  --data-urlencode "updated_since=2026-10-19T10:00:00Z"

{
  "data": [
    {
      "device_role": "router",
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "inserted_at": "2026-01-15T19:44:25Z",
      "ip_address": "10.0.0.1",
      "monitoring_enabled": true,
      "name": "Core Router",
      "site_id": "550e8400-e29b-41d4-a716-446655440000",
      "snmp_enabled": true,
      "snmp_version": "2c"
    }
  ],
  "meta": {
    "next_cursor": null,
    "page": 1,
    "per_page": 50,
    "total_count": 1,
    "total_pages": 1,
    "window": {
      "as_of": "2026-10-20T10:00:00Z",
      "field": "updated_at",
      "mode": "range",
      "since": "2026-10-19T10:00:00Z",
      "until": "2026-10-20T10:00:00Z"
    }
  }
}

Creates a device in the authenticated organization. `organization_id` is always taken from the token, so a value sent in the body is ignored. `site_id` is optional for an unrestricted token and, when given, must name a site in the same organization. A site-restricted token must provide a site in its own restriction; an omitted, `null`, or out-of-scope site is rejected as `not_found`. `check_interval_seconds` defaults to 300 and must be between 300 and 3600; outside that range the request is rejected with `unprocessable_entity`. Creating a device with `snmp_enabled` true also enqueues an SNMP discovery job in the background; the response does not wait for it.

Requires scope devices:write

Responses

201 application/json

The created device. The body carries the collection field set, so `description` and `check_interval_seconds` are omitted here even when they were sent.

400 application/json

The `device` parameter is missing

401 application/json

Missing, malformed, expired or revoked credentials

402 application/json

The plan's device limit is reached (`plan_limit`; `error.details` carries `current`, `limit` and `upgrade_url`)

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

The referenced `site_id` is not in this organization or outside the token's site restriction

409 application/json

A device with this IP address already exists at this site

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X POST https://staging.towerops.net/api/v1/devices \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "device": {
    "check_interval_seconds": 0,
    "description": "string",
    "device_role": "router",
    "eol_on": "string",
    "ip_address": "string",
    "monitoring_enabled": true,
    "name": "string",
    "purchased_on": "string",
    "site_id": "550e8400-e29b-41d4-a716-446655440000",
    "snmp_community": "string",
    "snmp_enabled": true,
    "snmp_port": 0,
    "snmp_version": "1",
    "snmpv3_auth_password": "string",
    "snmpv3_auth_protocol": "string",
    "snmpv3_priv_password": "string",
    "snmpv3_priv_protocol": "string",
    "snmpv3_security_level": "string",
    "snmpv3_username": "string",
    "warranty_expires_on": "string"
  }
}'

{
  "data": {
    "device_role": "router",
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "inserted_at": "2026-01-15T19:44:25Z",
    "ip_address": "10.0.0.1",
    "monitoring_enabled": true,
    "name": "Core Router",
    "site_id": "550e8400-e29b-41d4-a716-446655440000",
    "snmp_enabled": true,
    "snmp_version": "2c"
  }
}

Applies one fleet write to `device_ids` in a single request (issue 1906): exactly one of `site_id`, `lifecycle` (`paused`/`retired`) or `agent_token_id`. One call applies the same write every UI bulk action performs, including the same webhook events, so a nightly inventory sync costs one request per pass against the organization budget. The response reports the outcome per id under `results` (in request order) plus `updated_ids`/`skipped_ids`: an id outside the caller's site restriction, not in the organization, or a no-op for the operation reports `skipped`, and skipped ids never roll back the updated ones. A `site_id` destination outside the token's site restriction or the organization answers `not_found`; a `site_id` move that would collide an IP is rejected before any write. `Idempotency-Key` is honoured like every other write.

Requires scope devices:write

Responses

200 application/json

Per-id outcome

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

The destination site does not exist here or is outside the token's site restriction

409 application/json

A destination site's address is already in use

422 application/json

Missing/ambiguous operation, bad lifecycle, non-UUID or over-cap device_ids

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X PATCH https://staging.towerops.net/api/v1/devices/bulk \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "lifecycle": "paused",
  "site_id": "550e8400-e29b-41d4-a716-446655440000"
}'

{
  "data": {
    "results": [
      {
        "device_id": "550e8400-e29b-41d4-a716-446655440000",
        "result": "string"
      }
    ],
    "skipped": 0,
    "skipped_ids": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "updated": 0,
    "updated_ids": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  }
}

Gets one device by ID. The detail shape adds `description`, `check_interval_seconds`, and `monitoring_history`: 24-hour and seven-day coverage, each window's longest recovered gap, and the five latest poll failures and recovered gaps. SNMP secrets are never returned: the body reports only `snmpv3_auth_password_set` and `snmpv3_priv_password_set`.

Requires scope devices:read

Responses

200 application/json

The device

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No device with that ID in this organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl https://staging.towerops.net/api/v1/devices/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "check_interval_seconds": 0,
    "description": "string",
    "device_role": "router",
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "inserted_at": "2026-01-15T19:44:25Z",
    "ip_address": "10.0.0.1",
    "monitoring_enabled": true,
    "monitoring_history": {
      "last_24_hours": {
        "coverage_percent": 0.0,
        "expected": 0,
        "from": "2026-01-15T19:44:25Z",
        "has_data": true,
        "longest_gap": {
          "duration_seconds": null,
          "ended_at": null,
          "id": null,
          "started_at": null
        },
        "observed": 0,
        "to": "2026-01-15T19:44:25Z"
      },
      "last_7_days": {
        "coverage_percent": 0.0,
        "expected": 0,
        "from": "2026-01-15T19:44:25Z",
        "has_data": true,
        "longest_gap": {
          "duration_seconds": null,
          "ended_at": null,
          "id": null,
          "started_at": null
        },
        "observed": 0,
        "to": "2026-01-15T19:44:25Z"
      },
      "recent_poll_failures": [
        {
          "id": null,
          "message": null,
          "started_at": null
        }
      ],
      "recent_poll_gaps": [
        {
          "duration_seconds": null,
          "ended_at": null,
          "id": null,
          "started_at": null
        }
      ]
    },
    "name": "Core Router",
    "site_id": "550e8400-e29b-41d4-a716-446655440000",
    "snmp_enabled": true,
    "snmp_version": "2c"
  }
}

Updates the given attributes of a device. Omitted attributes are left alone. `site_id`, when given, must name a site in the same organization and be inside the caller's site restriction. A site-restricted caller cannot clear a device's site with `null`; out-of-scope or siteless changes are rejected with `not_found`. `check_interval_seconds` must be between 300 and 3600; outside that range the request is rejected with `unprocessable_entity`.

Requires scope devices:write

Responses

200 application/json

The updated device

400 application/json

The `device` parameter is missing

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No device with that ID in this organization, or the referenced `site_id` is not in this organization or outside the token's site restriction

409 application/json

A device with this IP address already exists at this site

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X PATCH https://staging.towerops.net/api/v1/devices/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "device": {
    "check_interval_seconds": 0,
    "description": "string",
    "device_role": "router",
    "eol_on": "string",
    "ip_address": "string",
    "monitoring_enabled": true,
    "name": "string",
    "purchased_on": "string",
    "site_id": "550e8400-e29b-41d4-a716-446655440000",
    "snmp_community": "string",
    "snmp_enabled": true,
    "snmp_port": 0,
    "snmp_version": "1",
    "snmpv3_auth_password": "string",
    "snmpv3_auth_protocol": "string",
    "snmpv3_priv_password": "string",
    "snmpv3_priv_protocol": "string",
    "snmpv3_security_level": "string",
    "snmpv3_username": "string",
    "warranty_expires_on": "string"
  }
}'

{
  "data": {
    "check_interval_seconds": 0,
    "description": "string",
    "device_role": "router",
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "inserted_at": "2026-01-15T19:44:25Z",
    "ip_address": "10.0.0.1",
    "monitoring_enabled": true,
    "monitoring_history": {
      "last_24_hours": {
        "coverage_percent": 0.0,
        "expected": 0,
        "from": "2026-01-15T19:44:25Z",
        "has_data": true,
        "longest_gap": {
          "duration_seconds": null,
          "ended_at": null,
          "id": null,
          "started_at": null
        },
        "observed": 0,
        "to": "2026-01-15T19:44:25Z"
      },
      "last_7_days": {
        "coverage_percent": 0.0,
        "expected": 0,
        "from": "2026-01-15T19:44:25Z",
        "has_data": true,
        "longest_gap": {
          "duration_seconds": null,
          "ended_at": null,
          "id": null,
          "started_at": null
        },
        "observed": 0,
        "to": "2026-01-15T19:44:25Z"
      },
      "recent_poll_failures": [
        {
          "id": null,
          "message": null,
          "started_at": null
        }
      ],
      "recent_poll_gaps": [
        {
          "duration_seconds": null,
          "ended_at": null,
          "id": null,
          "started_at": null
        }
      ]
    },
    "name": "Core Router",
    "site_id": "550e8400-e29b-41d4-a716-446655440000",
    "snmp_enabled": true,
    "snmp_version": "2c"
  }
}

Deletes a device along with the checks and results that hang off it.

Requires scope devices:write

Responses

200 application/json

The device was deleted

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No device with that ID in this organization

422 application/json

The device could not be deleted

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X DELETE https://staging.towerops.net/api/v1/devices/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "deleted": true
  }
}

Lists every check configured on the device, each with the status, value and timestamp of its most recent result. Unlike `GET /api/v1/checks` this includes the internally managed SNMP check types. `enabled` and `alerting` are different columns: a disarmed check still runs and still reports a status here, it just never pages. `latest_status`, `latest_value` and `latest_checked_at` are null while a check has not produced a result yet.

Requires scope checks:read

Responses

200 application/json

Checks on the device

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No device with that ID

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl https://staging.towerops.net/api/v1/devices/$DEVICE_ID/checks \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": [
    {
      "alerting": true,
      "check_type": "string",
      "enabled": true,
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "interval_seconds": 0,
      "latest_checked_at": "2026-01-15T19:44:25Z",
      "latest_status": "string",
      "latest_value": 0.0,
      "name": "string"
    }
  ]
}

Lists the interfaces SNMP discovery has recorded for the device. `data` is an empty list when the device has no SNMP record yet, because SNMP is disabled on it, or because discovery has not run. A device that belongs to another organization answers `404`, the same as one that does not exist at all, telling a caller that a device id it cannot read nevertheless exists would be an enumeration oracle.

Requires scope devices:read

Responses

200 application/json

Interfaces on the device

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No device with that ID

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl https://staging.towerops.net/api/v1/devices/$DEVICE_ID/interfaces \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "if_admin_status": "string",
      "if_alias": "string",
      "if_descr": "string",
      "if_index": 0,
      "if_name": "string",
      "if_oper_status": "string",
      "if_speed": 0,
      "monitored": true
    }
  ]
}

Returns one time series per matching check on the device, each point carrying the result's `timestamp`, `value` and `status`. The window ends now and reaches back `hours` hours; it defaults to the last 24 hours and is clamped to 1-720 hours (30 days) regardless of the requested value. A `hours` value that is not a number falls back to the default rather than failing. The series always spans the whole requested window: when the window holds more raw results than the response should carry, at most 2,000 points per check and 20,000 across the device, the series is downsampled (newest point plus evenly spread older points) rather than cut short. A device that belongs to another organization answers `404`, the same as one that does not exist at all, telling a caller that a device id it cannot read nevertheless exists would be an enumeration oracle.

Requires scope devices:read

Responses

200 application/json

One series per matching check

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No device with that ID

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -G https://staging.towerops.net/api/v1/devices/$DEVICE_ID/metrics \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-urlencode "check_type=snmp_sensor" \
  --data-urlencode "hours=24" \
  --data-urlencode "sensor_type=VALUE"

{
  "data": [
    {
      "check_id": "550e8400-e29b-41d4-a716-446655440000",
      "check_name": "string",
      "check_type": "string",
      "data": [
        {
          "status": "string",
          "timestamp": "2026-01-15T19:44:25Z",
          "value": 0.0
        }
      ]
    }
  ]
}

Lists service checks for the authenticated organization. Only the service check types (`http`, `tcp`, `dns`, `ping`) are exposed over the API; SNMP checks are managed internally and never appear in this list, the type filter is applied in SQL, so the page window and `meta.total_count` cover the service checks only, even with an explicit `check_type` filter. Pagination works like the other collection endpoints: `page`/`per_page` (per page defaults to 100 and is capped at 100), or an opaque `cursor` from `meta.next_cursor`, which takes precedence. `meta` is always present. A cursor that does not decode is rejected with `bad_request`.

Requires scope checks:read

Responses

200 application/json

Checks

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -G https://staging.towerops.net/api/v1/checks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-urlencode "check_type=http" \
  --data-urlencode "cursor=VALUE" \
  --data-urlencode "device_id=VALUE" \
  --data-urlencode "page=1" \
  --data-urlencode "per_page=50"

{
  "data": [
    {
      "alerting": true,
      "check_type": "http",
      "config": {
        "expected_status": 200,
        "url": "https://example.com/health"
      },
      "current_state": "ok",
      "current_state_type": "hard",
      "enabled": true,
      "id": "880e8400-e29b-41d4-a716-446655440003",
      "interval_seconds": 60,
      "name": "HTTPS health"
    }
  ],
  "meta": {
    "next_cursor": null,
    "page": 1,
    "per_page": 50,
    "total_count": 1,
    "total_pages": 1
  }
}

Creates a service check in the authenticated organization. `check_type` must be one of `http`, `tcp`, `dns` or `ping`; any other type, including the internally managed SNMP types, is rejected with `bad_request`. A `device_id` that belongs to another organization is rejected with `403`. Probe details go in `config` and are type-specific, e.g. `url` and `expected_status` for an `http` check, or `host` and `port` for `tcp`. `interval_seconds` and `retry_interval_seconds` must be at least 30. `timeout_ms` must be between 1 and 30000. Unsafe execution bounds return `unprocessable_entity` with field-level validation errors. `enabled` and `alerting` are different columns: `enabled` controls whether the check runs at all, `alerting` whether a failure raises an alert. A check created with `enabled` true is scheduled immediately.

Requires scope checks:write

Responses

201 application/json

The created check

400 application/json

The `check` parameter is missing, or `check_type` is not a service check type

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X POST https://staging.towerops.net/api/v1/checks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "check": {
    "agent_token_id": "550e8400-e29b-41d4-a716-446655440000",
    "alerting": true,
    "check_type": "http",
    "config": null,
    "description": "string",
    "device_id": "550e8400-e29b-41d4-a716-446655440000",
    "enabled": true,
    "interval_seconds": 0,
    "max_check_attempts": 0,
    "name": "string",
    "retry_interval_seconds": 0,
    "timeout_ms": 0
  }
}'

{
  "data": {
    "alerting": true,
    "check_type": "http",
    "config": {
      "expected_status": 200,
      "url": "https://example.com/health"
    },
    "current_state": "ok",
    "current_state_type": "hard",
    "enabled": true,
    "id": "880e8400-e29b-41d4-a716-446655440003",
    "interval_seconds": 60,
    "name": "HTTPS health"
  }
}

Gets one check by ID. `config` carries the type-specific probe settings and `alerting` reports whether the check is armed, independently of `enabled`. A check that has been deleted answers `not_found`, and so does an internally managed SNMP check: this endpoint exposes service checks only.

Requires scope checks:read

Responses

200 application/json

The check

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No check with that ID in this organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl https://staging.towerops.net/api/v1/checks/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "alerting": true,
    "check_type": "http",
    "config": {
      "expected_status": 200,
      "url": "https://example.com/health"
    },
    "current_state": "ok",
    "current_state_type": "hard",
    "enabled": true,
    "id": "880e8400-e29b-41d4-a716-446655440003",
    "interval_seconds": 60,
    "name": "HTTPS health"
  }
}

Updates the given attributes of a check. Omitted attributes are left alone. `check_type` is identity, not a setting, and is ignored here: a payload that carries it changes nothing, so a check can never be re-typed over the API (including onto an internally managed SNMP type). `alerting` is handled apart from the rest of the payload: it must be a boolean, or the strings `"true"`/`"false"` for form-encoded requests. Anything else is refused with `bad_request` rather than defaulted. Disarming a check also resolves the alerts it has open, so it stops escalating; it does not stop the check running, that is `enabled`. The rest of the update is applied first, so a payload rejected with `unprocessable_entity` leaves the arming state untouched. Execution and retry intervals must be at least 30 seconds; `timeout_ms` must be between 1 and 30000, just as on creation.

Requires scope checks:write

Responses

200 application/json

The updated check

400 application/json

The `check` parameter is missing, or `alerting` was neither true nor false

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No check with that ID in this organization

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X PATCH https://staging.towerops.net/api/v1/checks/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "check": {
    "agent_token_id": "550e8400-e29b-41d4-a716-446655440000",
    "alerting": true,
    "check_type": "http",
    "config": null,
    "description": "string",
    "device_id": "550e8400-e29b-41d4-a716-446655440000",
    "enabled": true,
    "interval_seconds": 0,
    "max_check_attempts": 0,
    "name": "string",
    "retry_interval_seconds": 0,
    "timeout_ms": 0
  }
}'

{
  "data": {
    "alerting": true,
    "check_type": "http",
    "config": {
      "expected_status": 200,
      "url": "https://example.com/health"
    },
    "current_state": "ok",
    "current_state_type": "hard",
    "enabled": true,
    "id": "880e8400-e29b-41d4-a716-446655440003",
    "interval_seconds": 60,
    "name": "HTTPS health"
  }
}

Deletes a check and cancels any jobs already scheduled for it.

Requires scope checks:write

Responses

200 application/json

The check was deleted

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No check with that ID in this organization

422 application/json

The check could not be deleted

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X DELETE https://staging.towerops.net/api/v1/checks/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "deleted": true
  }
}

Lists alerts for the authenticated organization, most recently triggered first, one page at a time. Pagination works like the other collection endpoints: `page`/`per_page` (per page defaults to 100 and is capped at 100), or an opaque `cursor` from `meta.next_cursor`, which takes precedence. `meta` carries the page, `total_count` and the next cursor. A cursor that does not decode is rejected with `bad_request`. A `page` past the last one returns an empty `data`, so paging until the list is empty terminates. By default history is capped at the last seven days, except that an alert which is still unresolved is always listed no matter how old it is. `triggered_since`/`triggered_until` (ISO 8601 with an offset) replace that default with an explicit inclusive `triggered_at` range, resolved alerts older than a week inside the range are listed too. An omitted `triggered_until` closes at the request's `as_of`, rows and `meta.total_count` alike, so `meta.window.until` equals `as_of`. A write committed after `as_of` can carry an earlier `triggered_at`, so resume a few minutes before `as_of`; the overlap is idempotent. `meta.window` echoes the exact bounds the query applied. An unparseable or inverted bound is rejected with `bad_request`. `subscriber_impact` is a nullable object, not a subscriber count. Totals, level amounts and individual subscriber revenue are included only for a user allowed to view financials; partner apps never receive revenue. `platform_degraded` records whether TowerOps was degraded when the alert was created. It remains true after recovery, rather than tracking current health.

Requires scope alerts:read

Responses

200 application/json

Alerts

400 application/json

The `cursor` parameter did not decode, or a `triggered_since`/`triggered_until` bound was unparseable, a non-string value, or inverted

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -G https://staging.towerops.net/api/v1/alerts \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-urlencode "cursor=VALUE" \
  --data-urlencode "device_id=VALUE" \
  --data-urlencode "page=1" \
  --data-urlencode "per_page=50" \
  --data-urlencode "status=active" \
  --data-urlencode "triggered_since=2026-10-13T00:00:00Z" \
  --data-urlencode "triggered_until=2026-10-20T00:00:00Z"

{
  "data": [
    {
      "acknowledged_at": null,
      "alert_type": "device_down",
      "device_name": "Core Router",
      "id": "bb0e8400-e29b-41d4-a716-446655440005",
      "message": "Core Router is not responding to ICMP",
      "platform_degraded": false,
      "resolved_at": null,
      "triggered_at": "2026-01-15T19:44:25Z"
    }
  ],
  "meta": {
    "next_cursor": null,
    "page": 1,
    "per_page": 50,
    "total_count": 1,
    "total_pages": 1,
    "window": {
      "as_of": "2026-10-20T10:00:00Z",
      "field": "updated_at",
      "mode": "range",
      "since": "2026-10-19T10:00:00Z",
      "until": "2026-10-20T10:00:00Z"
    }
  }
}

Gets one alert by ID. Alerts belonging to another organization are reported as not found.

Requires scope alerts:read

Responses

200 application/json

The alert

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No alert with that ID in this organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl https://staging.towerops.net/api/v1/alerts/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "acknowledged_at": null,
    "alert_type": "device_down",
    "device_name": "Core Router",
    "id": "bb0e8400-e29b-41d4-a716-446655440005",
    "message": "Core Router is not responding to ICMP",
    "platform_degraded": false,
    "resolved_at": null,
    "triggered_at": "2026-01-15T19:44:25Z"
  }
}

Marks an alert as acknowledged and returns the updated alert with `200`, in the usual `data` envelope, not `202`, and not an empty body. The acknowledging user is taken from the session behind the token, so `acknowledged_by_email` is only populated when the request carries one; otherwise the alert is acknowledged without an attributed user.

Requires scope alerts:write

Responses

200 application/json

The acknowledged alert

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No alert with that ID in this organization

422 application/json

The alert could not be acknowledged

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X POST https://staging.towerops.net/api/v1/alerts/$ID/acknowledge \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "acknowledged_at": null,
    "alert_type": "device_down",
    "device_name": "Core Router",
    "id": "bb0e8400-e29b-41d4-a716-446655440005",
    "message": "Core Router is not responding to ICMP",
    "platform_degraded": false,
    "resolved_at": null,
    "triggered_at": "2026-01-15T19:44:25Z"
  }
}

Pages the next on-call level for the alert's active escalation now and returns the alert with `200` in the usual `data` envelope, the level itself lives on the on-call incident, not on the alert. Refused with `unprocessable_entity` when the alert has no active escalation or the policy is already at its last level, matching the UI's Escalate button.

Requires scope alerts:write

Responses

200 application/json

The escalated alert

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No alert with that ID in this organization

422 application/json

No escalation to advance

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X POST https://staging.towerops.net/api/v1/alerts/$ID/escalate \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "acknowledged_at": null,
    "alert_type": "device_down",
    "device_name": "Core Router",
    "id": "bb0e8400-e29b-41d4-a716-446655440005",
    "message": "Core Router is not responding to ICMP",
    "platform_degraded": false,
    "resolved_at": null,
    "triggered_at": "2026-01-15T19:44:25Z"
  }
}

Records an operator note ("what I did") on the alert and returns it with `200` in the usual `data` envelope. Notes are attributed to the user behind the token when there is one, timestamped, listed oldest-first in the single-alert response, and kept on the alert after it resolves.

Requires scope alerts:write

Responses

200 application/json

The created note

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No alert with that ID in this organization

422 application/json

The note is empty or too long

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X POST https://staging.towerops.net/api/v1/alerts/$ID/notes \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "note": {
    "body": "string"
  }
}'

{
  "data": {
    "alert_id": "bb0e8400-e29b-41d4-a716-446655440005",
    "author_email": "noc@example.com",
    "body": "Dispatched a tech at 14:20; power company notified.",
    "id": "bb0e8400-e29b-41d4-a716-4466554400cc",
    "inserted_at": "2026-01-15T19:44:30Z",
    "user_id": "bb0e8400-e29b-41d4-a716-4466554400bb"
  }
}

Marks an alert as resolved and returns the updated alert with `200` in the usual `data` envelope, with `resolved_at` set. Resolving does not require the alert to have been acknowledged first.

Requires scope alerts:write

Responses

200 application/json

The resolved alert

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No alert with that ID in this organization

422 application/json

The alert could not be resolved

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X POST https://staging.towerops.net/api/v1/alerts/$ID/resolve \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "acknowledged_at": null,
    "alert_type": "device_down",
    "device_name": "Core Router",
    "id": "bb0e8400-e29b-41d4-a716-446655440005",
    "message": "Core Router is not responding to ICMP",
    "platform_degraded": false,
    "resolved_at": null,
    "triggered_at": "2026-01-15T19:44:25Z"
  }
}

Silences an alert for `minutes` from now and returns the updated alert with `200` in the usual `data` envelope, with `snoozed_until` set. The alert stays open and visible under the `snoozed` status filter but stops paging. `minutes` is clamped to one week, matching the UI's own cap; snoozing a resolved alert is refused with `unprocessable_entity`.

Requires scope alerts:write

Responses

200 application/json

The snoozed alert

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No alert with that ID in this organization

422 application/json

The alert could not be snoozed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X POST https://staging.towerops.net/api/v1/alerts/$ID/snooze \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "snooze": {
    "minutes": 0
  }
}'

{
  "data": {
    "acknowledged_at": null,
    "alert_type": "device_down",
    "device_name": "Core Router",
    "id": "bb0e8400-e29b-41d4-a716-446655440005",
    "message": "Core Router is not responding to ICMP",
    "platform_degraded": false,
    "resolved_at": null,
    "triggered_at": "2026-01-15T19:44:25Z"
  }
}

Lists every agent token in the authenticated organization. The list is not paginated and never includes the raw token.

Requires scope agents:read

Responses

200 application/json

Agents

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

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

{
  "data": [
    {
      "enabled": true,
      "expires_at": "2027-01-15T19:44:25Z",
      "id": "aa0e8400-e29b-41d4-a716-446655440004",
      "last_ip": "203.0.113.7",
      "last_seen_at": "2026-01-15T19:44:25Z",
      "name": "noc-poller-1"
    }
  ]
}

Creates an agent token in the authenticated organization. Unlike the resourceful endpoints the body is sent unwrapped: `name` is read from the top level of the request, not from under an `agent` key. Only `name` is read; any other attribute in the body is ignored. The response carries the raw bearer token under `data.token`. It is returned exactly once, at creation, and cannot be retrieved afterwards, store it now.

Requires scope agents:write

Responses

201 application/json

The created agent, including its raw token

400 application/json

The `name` parameter is missing

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

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

{
  "data": {
    "enabled": true,
    "expires_at": "2027-01-15T19:44:25Z",
    "id": "aa0e8400-e29b-41d4-a716-446655440004",
    "last_ip": "203.0.113.7",
    "last_seen_at": "2026-01-15T19:44:25Z",
    "name": "noc-poller-1",
    "token": "string"
  }
}

Gets one agent by ID, with `device_count`: the number of devices currently assigned to it. The raw token is never returned here.

Requires scope agents:read

Responses

200 application/json

The agent

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No agent with that ID in this organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

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

{
  "data": {
    "device_count": 0,
    "enabled": true,
    "expires_at": "2027-01-15T19:44:25Z",
    "id": "aa0e8400-e29b-41d4-a716-446655440004",
    "last_ip": "203.0.113.7",
    "last_seen_at": "2026-01-15T19:44:25Z",
    "name": "noc-poller-1"
  }
}

Deletes an agent token. The agent can no longer connect; devices assigned to it are not deleted. Success is 200 with `{"data": {"deleted": true}}`.

Requires scope agents:write

Responses

200 application/json

The agent was deleted

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No agent with that ID in this organization

422 application/json

The agent could not be deleted

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X DELETE https://staging.towerops.net/api/v1/agents/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "deleted": true
  }
}

Returns the organization the API token belongs to, including its default SNMP and RouterOS settings. Secrets are never returned: the stored SNMP community is reported only as the boolean `snmp_community_set`.

Requires scope organization:read

Responses

200 application/json

The organization

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

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

{
  "data": {
    "default_agent_token_id": "550e8400-e29b-41d4-a716-446655440000",
    "device_count": 0,
    "device_limit": 0,
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "mikrotik_enabled": true,
    "mikrotik_port": 0,
    "mikrotik_ssh_port": 0,
    "mikrotik_use_ssl": true,
    "mikrotik_username": "string",
    "name": "string",
    "slug": "string",
    "snmp_community_set": true,
    "snmp_port": 0,
    "snmp_transport": "udp",
    "snmp_version": "string",
    "snmpv3_auth_protocol": "string",
    "snmpv3_priv_protocol": "string",
    "snmpv3_security_level": "string",
    "snmpv3_username": "string",
    "subscription_plan": "string",
    "temperature_units": "celsius",
    "updated_at": "2026-01-15T19:44:25Z",
    "use_sites": true,
    "weather_units": "imperial"
  }
}

Updates organization settings. Omitted attributes are left alone. Beyond the `organization:write` scope this endpoint also checks the user behind the token: only an organization owner (or a superuser) may change settings, so an otherwise valid token belonging to a non-owner is rejected with `403`.

Requires scope organization:write

Responses

200 application/json

The updated organization

400 application/json

The `organization` parameter is missing

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X PATCH https://staging.towerops.net/api/v1/organization \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "organization": {
    "alert_routing": "string",
    "default_agent_token_id": "550e8400-e29b-41d4-a716-446655440000",
    "default_escalation_policy_id": "550e8400-e29b-41d4-a716-446655440000",
    "mikrotik_enabled": true,
    "mikrotik_password": "string",
    "mikrotik_port": 0,
    "mikrotik_ssh_port": 0,
    "mikrotik_use_ssl": true,
    "mikrotik_username": "string",
    "name": "string",
    "snmp_community": "string",
    "snmp_port": 0,
    "snmp_transport": "udp",
    "snmp_version": "string",
    "snmpv3_auth_password": "string",
    "snmpv3_auth_protocol": "string",
    "snmpv3_priv_password": "string",
    "snmpv3_priv_protocol": "string",
    "snmpv3_security_level": "string",
    "snmpv3_username": "string",
    "temperature_units": "celsius",
    "use_sites": true,
    "weather_units": "imperial"
  }
}'

{
  "data": {
    "default_agent_token_id": "550e8400-e29b-41d4-a716-446655440000",
    "device_count": 0,
    "device_limit": 0,
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "mikrotik_enabled": true,
    "mikrotik_port": 0,
    "mikrotik_ssh_port": 0,
    "mikrotik_use_ssl": true,
    "mikrotik_username": "string",
    "name": "string",
    "slug": "string",
    "snmp_community_set": true,
    "snmp_port": 0,
    "snmp_transport": "udp",
    "snmp_version": "string",
    "snmpv3_auth_protocol": "string",
    "snmpv3_priv_protocol": "string",
    "snmpv3_security_level": "string",
    "snmpv3_username": "string",
    "subscription_plan": "string",
    "temperature_units": "celsius",
    "updated_at": "2026-01-15T19:44:25Z",
    "use_sites": true,
    "weather_units": "imperial"
  }
}

Lists the users who belong to the authenticated organization, with their roles. The list is not paginated. Each member's `id` is that user's ID, which is what the member endpoints take in the path.

Requires scope members:read

Responses

200 application/json

Members

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

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

{
  "data": [
    {
      "email": "string",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "inserted_at": "2026-01-15T19:44:25Z",
      "role": "string",
      "site_ids": [
        "string"
      ]
    }
  ]
}

Changes the role of one member of the authenticated organization, their site restriction, or both, and returns the updated membership. The body is sent unwrapped: `role` and `site_ids` are read from the top level, not from under a `member` key. `site_ids` is the complete list of site ids the member may see, `[]` lifts the restriction back to the whole organization (issue 1775). The owner cannot be site-restricted, and a caller whose own membership is fenced can only grant sites inside their own list. Authorization is checked against the user behind the token as well as the scope, and every one of these failures is a `403`: the caller is not an owner or admin of the organization; the target member is the owner, whose role cannot be changed; the caller is not an owner and tried to grant `owner`; or the caller tried to assign a role more privileged than their own. Changing your own role is not itself blocked, the same rules apply as for anyone else.

Requires scope members:write

Responses

200 application/json

The updated membership

400 application/json

Neither `role` nor `site_ids` was sent

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No member with that user ID in this organization

422 application/json

The requested role is not a valid role

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X PATCH https://staging.towerops.net/api/v1/members/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "role": "admin",
  "site_ids": [
    "<site-uuid>"
  ]
}'

{
  "data": {
    "email": "string",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "role": "string",
    "site_ids": [
      "string"
    ]
  }
}

Removes a user from the authenticated organization. Success is `200` with `{"data": {"deleted": true}}`. Only owners and admins may remove members, and the organization's owner can never be removed; both refusals are a `403`.

Requires scope members:write

Responses

200 application/json

The member was removed

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No member with that user ID in this organization

422 application/json

The member could not be removed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X DELETE https://staging.towerops.net/api/v1/members/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "deleted": true
  }
}

Lists invitations for the authenticated organization that have not yet been accepted. The list is not paginated and never includes the invitation token.

Requires scope members:read

Responses

200 application/json

Pending invitations

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

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

{
  "data": [
    {
      "email": "string",
      "expires_at": "2026-01-15T19:44:25Z",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "inserted_at": "2026-01-15T19:44:25Z",
      "invited_by_email": "string",
      "role": "string"
    }
  ]
}

Invites an email address to join the authenticated organization. The invitation expires one week after it is created. The body is sent unwrapped and both fields are required: `email` and `role` are read from the top level, not from under an `invitation` key, and a request missing either one is rejected with `400`. Authorization is checked against the user behind the token as well as the scope. All of these are a `403`: the token has no user, the user is not a member of the organization, the user is not an owner or admin, the requested role is not a known role name, or the requested role is more privileged than the caller's own. `owner` is a known role but not an assignable invitation one, so it is rejected as a validation failure with `422`. An address that is already a member is accepted: membership is not checked. An address with a live pending invitation is not: the partial unique index on pending invitations makes that a `422` with `already has a pending invitation`. Only an expired pending invitation is replaced by a new one.

Requires scope members:write

Responses

201 application/json

The created invitation

400 application/json

The `email` or `role` parameter is missing

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

422 application/json

Validation failed, e.g. a malformed email address or a role that is not assignable to an invitee

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X POST https://staging.towerops.net/api/v1/invitations \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "new.engineer@example.com",
  "role": "member"
}'

{
  "data": {
    "email": "string",
    "expires_at": "2026-01-15T19:44:25Z",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "invited_by_email": "string",
    "role": "string"
  }
}

Deletes a pending invitation so its link can no longer be redeemed. Success is 200 with `{"data": {"deleted": true}}`.

Requires scope members:write

Responses

200 application/json

The invitation was revoked

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No invitation with that ID in this organization

422 application/json

The invitation could not be deleted

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X DELETE https://staging.towerops.net/api/v1/invitations/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "deleted": true
  }
}

Lists every third-party integration configured for the authenticated organization. Not paginated: the full list is returned under `data` and no `meta` is present. Vendor credentials are write-only and are never read back out, so entries carry only the provider key, whether the integration is enabled, its sync interval and the outcome of the last sync.

Requires scope integrations:read

Responses

200 application/json

Integrations

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

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

{
  "data": [
    {
      "enabled": true,
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "inserted_at": "2026-01-15T19:44:25Z",
      "last_sync_message": "string",
      "last_sync_status": "string",
      "last_synced_at": "2026-01-15T19:44:25Z",
      "provider": "string",
      "sync_interval_minutes": 0,
      "updated_at": "2026-01-15T19:44:25Z"
    }
  ]
}

Configures a vendor integration for the authenticated organization. Omitting `sync_interval_minutes` uses the provider default: 30 minutes for NetBox, 15 for Gaiia and 10 for other providers. Updates preserve an existing interval unless the caller supplies a replacement. Quo with `enabled: true` provisions its listener before reporting success. Provisioning failure returns 422 but retains a disabled integration; retrieve it and update it to retry. Credentials supplied in the body are write-only: they are protected by database-level access control (not application-level encryption) and are never echoed back by this or any other endpoint. Attribute keys outside the supported allowlist are dropped silently rather than rejected.

Requires scope integrations:write

Responses

201 application/json

The created integration

400 application/json

The `integration` parameter is missing

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X POST https://staging.towerops.net/api/v1/integrations \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "integration": {
    "api_key": "string",
    "api_secret": "string",
    "api_token": "string",
    "api_url": "string",
    "client_id": "string",
    "client_secret": "string",
    "config": null,
    "enabled": true,
    "instance_url": "string",
    "provider": "string",
    "sync_interval_minutes": 0,
    "webhook_token": "string"
  }
}'

{
  "data": {
    "enabled": true,
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "last_sync_message": "string",
    "last_sync_status": "string",
    "last_synced_at": "2026-01-15T19:44:25Z",
    "provider": "string",
    "sync_interval_minutes": 0,
    "updated_at": "2026-01-15T19:44:25Z"
  }
}

Gets one integration by ID. Credentials are write-only and are not included.

Requires scope integrations:read

Responses

200 application/json

The integration

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No integration with that ID in this organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

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

{
  "data": {
    "enabled": true,
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "last_sync_message": "string",
    "last_sync_status": "string",
    "last_synced_at": "2026-01-15T19:44:25Z",
    "provider": "string",
    "sync_interval_minutes": 0,
    "updated_at": "2026-01-15T19:44:25Z"
  }
}

Updates the given attributes of an integration. Omitted attributes are left alone, and keys outside the supported allowlist are dropped silently. Credentials can be rotated by sending them again; they remain write-only and are not returned in the response. Enabling Quo provisions its listener first. Replacing its API key removes the previous workspace's subscription with the old key before saving the replacement. Failure returns 422 and leaves capture disabled; failed previous-workspace cleanup retains the old credentials for retry. Disabling rejects deliveries locally even if remote deletion fails.

Requires scope integrations:write

Responses

200 application/json

The updated integration

400 application/json

The `integration` parameter is missing

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No integration with that ID in this organization

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X PATCH https://staging.towerops.net/api/v1/integrations/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "integration": {
    "api_key": "string",
    "api_secret": "string",
    "api_token": "string",
    "api_url": "string",
    "client_id": "string",
    "client_secret": "string",
    "config": null,
    "enabled": true,
    "instance_url": "string",
    "provider": "string",
    "sync_interval_minutes": 0,
    "webhook_token": "string"
  }
}'

{
  "data": {
    "enabled": true,
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "last_sync_message": "string",
    "last_sync_status": "string",
    "last_synced_at": "2026-01-15T19:44:25Z",
    "provider": "string",
    "sync_interval_minutes": 0,
    "updated_at": "2026-01-15T19:44:25Z"
  }
}

Removes an integration and its stored credentials. Success is 200 with `{"data": {"deleted": true}}`.

Requires scope integrations:write

Responses

200 application/json

The integration was deleted

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No integration with that ID in this organization

422 application/json

The integration could not be deleted

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X DELETE https://staging.towerops.net/api/v1/integrations/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "deleted": true
  }
}

Runs a live credential check against the vendor with the integration's stored credentials and reports whether the vendor accepted them. On success the payload carries `status` (`"ok"`) and `provider`. Any failure rejected credentials, a provider that does not support connection testing, or an unexpected upstream status, comes back as `502 Bad Gateway` with a deliberately coarse message: upstream response bodies and credentials are kept server-side rather than relayed to the caller.

Requires scope integrations:write

Responses

200 application/json

The vendor accepted the credentials

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No integration with that ID in this organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

502 application/json

The vendor rejected the credentials or could not be reached

curl -X POST https://staging.towerops.net/api/v1/integrations/$ID/test \
  -H "Authorization: Bearer YOUR_API_TOKEN"

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

Lists every RF coverage prediction in the authenticated organization. Not paginated: the whole list comes back under `data` and no `meta` is present. Every entry carries `status` and `progress_pct`, so Terraform and other IaC consumers can poll until a coverage reaches `ready` before treating it as healthy.

Requires scope coverages:read

Responses

200 application/json

Coverages

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

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

{
  "data": [
    {
      "antenna_slug": "rf-elements-tp-sh-30",
      "frequency_mhz": 5.8e3,
      "id": "cc0e8400-e29b-41d4-a716-446655440006",
      "name": "North sector 5 GHz",
      "progress_pct": 100,
      "status": "ready",
      "tx_power_dbm": 22.0
    }
  ]
}

Creates a coverage and immediately enqueues the compute pipeline, so the response is returned long before the prediction finishes. Poll `GET /api/v1/coverages/:id` on `status` until it becomes `ready`, the resource is designed for Terraform/IaC read-after-write reconciliation. The response is `201` even when compute could not be queued: the row is exposed anyway so a provider's read-after-write still reconciles, with `status` reflecting that nothing is running. Note the unit asymmetry on this frozen wire format: the request takes `frequency_ghz`, `radius_mi` and `height_agl_ft`, while the resource is returned as `frequency_mhz`, `radius_m` and `height_agl_m`.

Requires scope coverages:write

Responses

201 application/json

The created coverage, with compute queued

400 application/json

The `coverage` parameter is missing

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X POST https://staging.towerops.net/api/v1/coverages \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "coverage": {
    "antenna_slug": "string",
    "azimuth_deg": 0.0,
    "cable_loss_db": 0.0,
    "device_id": "550e8400-e29b-41d4-a716-446655440000",
    "downtilt_deg": 0.0,
    "foliage_tuning": 0.0,
    "frequency_ghz": 0.0,
    "height_agl_ft": 0.0,
    "latitude_override": 0.0,
    "longitude_override": 0.0,
    "name": "string",
    "radius_mi": 0.0,
    "rx_threshold_dbm": 0.0,
    "site_id": "550e8400-e29b-41d4-a716-446655440000",
    "sm_gain_dbi": 0.0,
    "tx_power_dbm": 0.0
  }
}'

{
  "data": {
    "antenna_slug": "rf-elements-tp-sh-30",
    "frequency_mhz": 5.8e3,
    "id": "cc0e8400-e29b-41d4-a716-446655440006",
    "name": "North sector 5 GHz",
    "progress_pct": 100,
    "status": "ready",
    "tx_power_dbm": 22.0
  }
}

Gets one coverage by ID, including `status`, `progress_pct`, `error_message`, the computed bounding box and the generated raster paths. This is the endpoint Terraform/IaC consumers poll on `status` until it reads `ready`.

Requires scope coverages:read

Responses

200 application/json

The coverage

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No coverage with that ID in this organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

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

{
  "data": {
    "antenna_slug": "rf-elements-tp-sh-30",
    "frequency_mhz": 5.8e3,
    "id": "cc0e8400-e29b-41d4-a716-446655440006",
    "name": "North sector 5 GHz",
    "progress_pct": 100,
    "status": "ready",
    "tx_power_dbm": 22.0
  }
}

Updates editable fields on a coverage. Omitted attributes are left alone. This does **not** recompute: the previously computed outputs stay as they are until you `POST /api/v1/coverages/:id/recompute`. As on create, input is given as `frequency_ghz`, `radius_mi` and `height_agl_ft` while the resource is returned in MHz and metres.

Requires scope coverages:write

Responses

200 application/json

The updated coverage

400 application/json

The `coverage` parameter is missing

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No coverage with that ID in this organization

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X PATCH https://staging.towerops.net/api/v1/coverages/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "coverage": {
    "antenna_slug": "string",
    "azimuth_deg": 0.0,
    "cable_loss_db": 0.0,
    "device_id": "550e8400-e29b-41d4-a716-446655440000",
    "downtilt_deg": 0.0,
    "foliage_tuning": 0.0,
    "frequency_ghz": 0.0,
    "height_agl_ft": 0.0,
    "latitude_override": 0.0,
    "longitude_override": 0.0,
    "name": "string",
    "radius_mi": 0.0,
    "rx_threshold_dbm": 0.0,
    "site_id": "550e8400-e29b-41d4-a716-446655440000",
    "sm_gain_dbi": 0.0,
    "tx_power_dbm": 0.0
  }
}'

{
  "data": {
    "antenna_slug": "rf-elements-tp-sh-30",
    "frequency_mhz": 5.8e3,
    "id": "cc0e8400-e29b-41d4-a716-446655440006",
    "name": "North sector 5 GHz",
    "progress_pct": 100,
    "status": "ready",
    "tx_power_dbm": 22.0
  }
}

Deletes a coverage and its computed artifacts. Success is 200 with `{"data": {"deleted": true}}`.

Requires scope coverages:write

Responses

200 application/json

The coverage was deleted

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No coverage with that ID in this organization

422 application/json

The coverage could not be deleted

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

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

{
  "data": {
    "deleted": true
  }
}

Returns the computed heatmap as a KMZ bundle (a ZIP holding `doc.kml` plus the `overlay.png` ground overlay) ready to open in Google Earth or any compatible viewer. The body is binary, not JSON, and is served as an attachment via `Content-Disposition: attachment; filename="coverage-<id>.kmz"`. Only a coverage whose `status` is `ready` and which has a rendered raster can be exported; anything else is rejected with `409 Conflict`, so poll `GET /api/v1/coverages/:id` until `ready` before downloading. Failures while assembling the bundle come back as `500` with a generic message, since the underlying filesystem and archive details stay server-side.

Requires scope coverages:read

Responses

200 application/vnd.google-earth.kmz

KMZ bundle

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No coverage with that ID in this organization

409 application/json

The coverage has not finished computing

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

500 application/json

The KMZ bundle could not be built

curl https://staging.towerops.net/api/v1/coverages/$ID/kmz \
  -H "Authorization: Bearer YOUR_API_TOKEN"

"string"

Re-runs the compute pipeline for an existing coverage without changing its parameters, useful from Terraform after an apply when you want a fresh heatmap against current terrain and clutter data. Accepted asynchronously: the returned coverage has `status` set to the queued state, and consumers poll `GET /api/v1/coverages/:id` until it reaches `ready`. A coverage that is already computing is rejected with `409 Conflict` rather than queued twice.

Requires scope coverages:write

Responses

202 application/json

Compute was queued

400 application/json

Compute could not be queued

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No coverage with that ID in this organization

409 application/json

A compute is already running for this coverage

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

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

{
  "data": {
    "antenna_slug": "rf-elements-tp-sh-30",
    "frequency_mhz": 5.8e3,
    "id": "cc0e8400-e29b-41d4-a716-446655440006",
    "name": "North sector 5 GHz",
    "progress_pct": 100,
    "status": "ready",
    "tx_power_dbm": 22.0
  }
}

Returns the unified activity feed for the authenticated organization, newest first, merging config changes, alert transitions, device events, integration syncs and device creation into one stream. Not paginated: the feed is capped by `limit` and no `meta` is present.

Requires scope activity:read

Responses

200 application/json

Activity entries

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -G https://staging.towerops.net/api/v1/activity \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-urlencode "limit=50" \
  --data-urlencode "types=alert_fired,alert_resolved"

{
  "data": [
    {
      "detail": "string",
      "device_name": "string",
      "icon": "string",
      "id": "string",
      "link": "string",
      "severity": "info",
      "site_name": "string",
      "summary": "string",
      "timestamp": "2026-01-15T19:44:25Z",
      "type": "config_change"
    }
  ]
}

One page of the organization's billing-mirrored customers (Gaiia, Splynx, Sonar, VISP), ordered by name. `q` matches name or account reference case-insensitively, and a phone number in any format matches the customer's normalized phone exactly. Walk the collection with `page` and `per_page`, or by sending back `meta.next_cursor`.

Requires scope subscribers:read

Responses

200 application/json

Customers

400 application/json

The `cursor` parameter did not decode

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -G https://staging.towerops.net/api/v1/customers \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-urlencode "cursor=VALUE" \
  --data-urlencode "page=VALUE" \
  --data-urlencode "per_page=VALUE" \
  --data-urlencode "provider=VALUE" \
  --data-urlencode "q=VALUE" \
  --data-urlencode "status=VALUE"

{
  "data": [
    {
      "email": "string",
      "external_id": "string",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "mrr": "string",
      "name": "string",
      "phone": "string",
      "provider": "gaiia",
      "reference": "string",
      "status": "string",
      "synced_at": "2026-01-15T19:44:25Z"
    }
  ],
  "meta": {
    "next_cursor": null,
    "page": 1,
    "per_page": 50,
    "total_count": 1,
    "total_pages": 1
  }
}

One customer by its stable TowerOps id. A customer the billing system withdrew is not found.

Requires scope subscribers:read

Responses

200 application/json

The customer

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No customer with that ID in this organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl https://staging.towerops.net/api/v1/customers/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "email": "string",
    "external_id": "string",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "mrr": "string",
    "name": "string",
    "phone": "string",
    "provider": "gaiia",
    "reference": "string",
    "status": "string",
    "synced_at": "2026-01-15T19:44:25Z"
  }
}

The subscriber trace the `/trace` page renders for this customer: the serving device and access point, the subscriber's wireless stations, the router connection (PPPoE session or DHCP assignment), QoE, open alerts and maintenance windows. By default this is the stored snapshot and the request touches no equipment; `connectivity` is `null`. With `probe=true` the request also runs the live connectivity checks through the organization's agents (router session, radio registration, Preseem, ping), which can take several seconds, and returns the evaluated checklist in `connectivity`. A customer whose billing provider has no subscriber trace (Sonar, VISP, or a provider record not yet mirrored) answers 404.

Requires scope subscribers:read

Responses

200 application/json

The trace

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No customer with that ID in this organization, or no trace for it

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -G https://staging.towerops.net/api/v1/customers/$ID/trace \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-urlencode "probe=VALUE"

{
  "data": {
    "access_point": null,
    "active_alert_count": 0,
    "active_alerts": [],
    "co_tenants": [],
    "connectivity": null,
    "customer_id": "550e8400-e29b-41d4-a716-446655440000",
    "device": null,
    "maintenance_windows": [],
    "qoe": null,
    "router_connection": null,
    "sector_verdict": "overcrowding",
    "stations": [],
    "subscriber": null
  }
}

The `/trace` page's search: subscriber accounts (by name, account id or phone number), inventory items, sites, devices and access points matching `q`, at most 25. A query shorter than two characters matches nothing. An account result that is mirrored in the customer registry carries its `customer_id`, which `GET /api/v1/customers/{id}/trace` takes.

Requires scope subscribers:read

Responses

200 application/json

Matches

400 application/json

The `q` parameter is missing

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -G https://staging.towerops.net/api/v1/trace/search \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-urlencode "q=VALUE"

{
  "data": [
    {
      "customer_id": "550e8400-e29b-41d4-a716-446655440000",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "label": "string",
      "matched_by": "phone",
      "sublabel": "string",
      "type": "account"
    }
  ]
}

Lists maintenance windows for the authenticated organization, newest first, one page at a time. Pagination works like the other collection endpoints: `page`/`per_page` (per page defaults to 100 and is capped at 100), or an opaque `cursor` from `meta.next_cursor`, which takes precedence. `meta` carries the page, `total_count` and the next cursor. A cursor that does not decode is rejected with `bad_request`. A `page` past the last one returns an empty `data`, so paging until the list is empty terminates.

Requires scope config:read

Responses

200 application/json

Maintenance windows

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -G https://staging.towerops.net/api/v1/maintenance_windows \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-urlencode "cursor=VALUE" \
  --data-urlencode "filter=active" \
  --data-urlencode "page=1" \
  --data-urlencode "per_page=50"

{
  "data": [
    {
      "announce_on_status_page": true,
      "device_id": "550e8400-e29b-41d4-a716-446655440000",
      "ends_at": "2026-01-15T19:44:25Z",
      "exclude_from_uptime": true,
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "inserted_at": "2026-01-15T19:44:25Z",
      "name": "string",
      "public_title": "string",
      "reason": "string",
      "recurrence_rule": "string",
      "recurring": true,
      "site_id": "550e8400-e29b-41d4-a716-446655440000",
      "starts_at": "2026-01-15T19:44:25Z",
      "suppress_alerts": true
    }
  ],
  "meta": {
    "next_cursor": null,
    "page": 1,
    "per_page": 50,
    "total_count": 1,
    "total_pages": 1
  }
}

Creates a maintenance window in the authenticated organization. The window is attributed to the user the API token belongs to, and `organization_id` and the creator are set from the token rather than the body. A partner-app token, which has no user behind it, is rejected with `403`. Scope the window to a single site or device with `site_id`/`device_id`; leave both out for an organization-wide window.

Requires scope config:write

Responses

201 application/json

The created maintenance window

400 application/json

The `maintenance_window` parameter is missing

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X POST https://staging.towerops.net/api/v1/maintenance_windows \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "maintenance_window": {
    "announce_on_status_page": true,
    "device_id": "550e8400-e29b-41d4-a716-446655440000",
    "ends_at": "2026-01-15T19:44:25Z",
    "exclude_from_uptime": true,
    "name": "string",
    "public_title": "string",
    "reason": "string",
    "recurrence_rule": "string",
    "recurring": true,
    "site_id": "550e8400-e29b-41d4-a716-446655440000",
    "starts_at": "2026-01-15T19:44:25Z",
    "suppress_alerts": true
  }
}'

{
  "data": {
    "announce_on_status_page": true,
    "device_id": "550e8400-e29b-41d4-a716-446655440000",
    "ends_at": "2026-01-15T19:44:25Z",
    "exclude_from_uptime": true,
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "name": "string",
    "public_title": "string",
    "reason": "string",
    "recurrence_rule": "string",
    "recurring": true,
    "site_id": "550e8400-e29b-41d4-a716-446655440000",
    "starts_at": "2026-01-15T19:44:25Z",
    "suppress_alerts": true
  }
}

Gets one maintenance window by ID.

Requires scope config:read

Responses

200 application/json

The maintenance window

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No maintenance window with that ID in this organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl https://staging.towerops.net/api/v1/maintenance_windows/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "announce_on_status_page": true,
    "device_id": "550e8400-e29b-41d4-a716-446655440000",
    "ends_at": "2026-01-15T19:44:25Z",
    "exclude_from_uptime": true,
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "name": "string",
    "public_title": "string",
    "reason": "string",
    "recurrence_rule": "string",
    "recurring": true,
    "site_id": "550e8400-e29b-41d4-a716-446655440000",
    "starts_at": "2026-01-15T19:44:25Z",
    "suppress_alerts": true
  }
}

Updates the given attributes of a maintenance window. Omitted attributes are left alone.

Requires scope config:write

Responses

200 application/json

The updated maintenance window

400 application/json

The `maintenance_window` parameter is missing

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No maintenance window with that ID in this organization

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X PATCH https://staging.towerops.net/api/v1/maintenance_windows/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "maintenance_window": {
    "announce_on_status_page": true,
    "device_id": "550e8400-e29b-41d4-a716-446655440000",
    "ends_at": "2026-01-15T19:44:25Z",
    "exclude_from_uptime": true,
    "name": "string",
    "public_title": "string",
    "reason": "string",
    "recurrence_rule": "string",
    "recurring": true,
    "site_id": "550e8400-e29b-41d4-a716-446655440000",
    "starts_at": "2026-01-15T19:44:25Z",
    "suppress_alerts": true
  }
}'

{
  "data": {
    "announce_on_status_page": true,
    "device_id": "550e8400-e29b-41d4-a716-446655440000",
    "ends_at": "2026-01-15T19:44:25Z",
    "exclude_from_uptime": true,
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "name": "string",
    "public_title": "string",
    "reason": "string",
    "recurrence_rule": "string",
    "recurring": true,
    "site_id": "550e8400-e29b-41d4-a716-446655440000",
    "starts_at": "2026-01-15T19:44:25Z",
    "suppress_alerts": true
  }
}

Deletes a maintenance window. Alerts are no longer suppressed for its scope once it is gone.

Requires scope config:write

Responses

200 application/json

The maintenance window was deleted

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No maintenance window with that ID in this organization

422 application/json

The maintenance window could not be deleted

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

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

{
  "data": {
    "deleted": true
  }
}

Lists every on-call schedule in the authenticated organization. This endpoint does not paginate and omits `meta`; each entry carries the schedule summary only, without its layers or overrides.

Requires scope config:read

Responses

200 application/json

Schedules

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

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

{
  "data": [
    {
      "description": "string",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "inserted_at": "2026-01-15T19:44:25Z",
      "name": "string",
      "timezone": "string"
    }
  ]
}

Creates an on-call schedule in the authenticated organization. The schedule is created empty: add rotation layers, layer members and overrides with the nested endpoints below.

Requires scope config:write

Responses

201 application/json

The created schedule

400 application/json

The `schedule` parameter is missing

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X POST https://staging.towerops.net/api/v1/schedules \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "schedule": {
    "description": "string",
    "name": "string",
    "timezone": "string"
  }
}'

{
  "data": {
    "description": "string",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "name": "string",
    "timezone": "string"
  }
}

Gets one schedule by ID. Unlike the list endpoint, this returns the full detail shape: every rotation layer with its ordered members (each member carrying the user it points at), plus recent and upcoming overrides with their users. Overrides that ended more than about two weeks ago are omitted, they can no longer affect the rendered schedule.

Requires scope config:read

Responses

200 application/json

The schedule

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No schedule with that ID in this organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl https://staging.towerops.net/api/v1/schedules/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "description": "string",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "layers": [
      {
        "handoff_day": 0,
        "handoff_time": "string",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "inserted_at": "2026-01-15T19:44:25Z",
        "members": [],
        "name": "string",
        "position": 0,
        "rotation_interval": 0,
        "rotation_type": "daily",
        "start_date": "2026-01-15"
      }
    ],
    "name": "string",
    "overrides": [
      {
        "accepted_at": "2026-01-15T19:44:25Z",
        "end_time": "2026-01-15T19:44:25Z",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "inserted_at": "2026-01-15T19:44:25Z",
        "pending": true,
        "reason": "string",
        "requested_by": {},
        "requested_by_id": "550e8400-e29b-41d4-a716-446655440000",
        "schedule_id": "550e8400-e29b-41d4-a716-446655440000",
        "start_time": "2026-01-15T19:44:25Z",
        "user": {
          "email": "noc@example.com",
          "id": "9d1a5c3e-1f2b-4c8a-9e7d-2b6f4a8c1d30"
        },
        "user_id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "timezone": "string"
  }
}

Updates the given attributes of a schedule. Omitted attributes are left alone. Layers, members and overrides are not touched here; use the nested endpoints. The response is the summary shape, without layers or overrides.

Requires scope config:write

Responses

200 application/json

The updated schedule

400 application/json

The `schedule` parameter is missing

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No schedule with that ID in this organization

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X PATCH https://staging.towerops.net/api/v1/schedules/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "schedule": {
    "description": "string",
    "name": "string",
    "timezone": "string"
  }
}'

{
  "data": {
    "description": "string",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "name": "string",
    "timezone": "string"
  }
}

Deletes a schedule along with its layers, layer members and overrides.

Requires scope config:write

Responses

200 application/json

The schedule was deleted

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No schedule with that ID in this organization

422 application/json

The schedule could not be deleted

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X DELETE https://staging.towerops.net/api/v1/schedules/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "deleted": true
  }
}

Adds a rotation layer to a schedule. Attributes are nested under a `layer` key. `schedule_id` is taken from the path and ignored in the body. Layers are evaluated in `position` order, so a higher-positioned layer takes precedence over the ones below it when both are active.

Requires scope config:write

Responses

201 application/json

The created layer

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No schedule with that ID in this organization

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X POST https://staging.towerops.net/api/v1/schedules/$ID/layers \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "layer": {
    "handoff_day": 0,
    "handoff_time": "string",
    "name": "string",
    "position": 0,
    "rotation_interval": 0,
    "rotation_type": "daily",
    "start_date": "2026-01-15"
  }
}'

{
  "data": {
    "handoff_day": 0,
    "handoff_time": "string",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "members": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "inserted_at": "2026-01-15T19:44:25Z",
        "layer_id": "550e8400-e29b-41d4-a716-446655440000",
        "position": 0,
        "user": {
          "email": "noc@example.com",
          "id": "9d1a5c3e-1f2b-4c8a-9e7d-2b6f4a8c1d30"
        },
        "user_id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "name": "string",
    "position": 0,
    "rotation_interval": 0,
    "rotation_type": "daily",
    "start_date": "2026-01-15"
  }
}

Updates the given attributes of a layer. Attributes are nested under a `layer` key; omitted attributes are left alone. The layer must belong to the schedule named in the path, otherwise the request answers 404.

Requires scope config:write

Responses

200 application/json

The updated layer

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

The schedule or the layer does not exist here

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X PATCH https://staging.towerops.net/api/v1/schedules/$ID/layers/$LAYER_ID \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "layer": {
    "handoff_day": 0,
    "handoff_time": "string",
    "name": "string",
    "position": 0,
    "rotation_interval": 0,
    "rotation_type": "daily",
    "start_date": "2026-01-15"
  }
}'

{
  "data": {
    "handoff_day": 0,
    "handoff_time": "string",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "members": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "inserted_at": "2026-01-15T19:44:25Z",
        "layer_id": "550e8400-e29b-41d4-a716-446655440000",
        "position": 0,
        "user": {
          "email": "noc@example.com",
          "id": "9d1a5c3e-1f2b-4c8a-9e7d-2b6f4a8c1d30"
        },
        "user_id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "name": "string",
    "position": 0,
    "rotation_interval": 0,
    "rotation_type": "daily",
    "start_date": "2026-01-15"
  }
}

Removes a layer from a schedule along with its members. The layer must belong to the schedule named in the path, otherwise the request answers 404. Success is 200 with `{"data": {"deleted": true}}`, not 204.

Requires scope config:write

Responses

200 application/json

The layer was deleted

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

The schedule or the layer does not exist here

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X DELETE https://staging.towerops.net/api/v1/schedules/$ID/layers/$LAYER_ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "deleted": true
  }
}

Adds a user to a layer's rotation. Attributes are nested under a `member` key; `layer_id` is taken from the path and ignored in the body. Members take their turn in `position` order.

Requires scope config:write

Responses

201 application/json

The created member

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

The schedule or the layer does not exist here

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X POST https://staging.towerops.net/api/v1/schedules/$ID/layers/$LAYER_ID/members \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "member": {
    "position": 0,
    "user_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}'

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "layer_id": "550e8400-e29b-41d4-a716-446655440000",
    "position": 0,
    "user": {
      "email": "noc@example.com",
      "id": "9d1a5c3e-1f2b-4c8a-9e7d-2b6f4a8c1d30"
    },
    "user_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Removes a user from a layer's rotation. The whole chain is checked: the layer must belong to the schedule and the member to the layer, otherwise the request answers 404. Success is 200 with `{"data": {"deleted": true}}`.

Requires scope config:write

Responses

200 application/json

The member was removed

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

The schedule, layer or member does not exist here

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X DELETE https://staging.towerops.net/api/v1/schedules/$ID/layers/$LAYER_ID/members/$MEMBER_ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "deleted": true
  }
}

Resolves the single user currently on call for the schedule, applying overrides over the rotation layers. When nobody is on call, no layers, no members in the active rotation, or the schedule has not started yet, the request still succeeds with `{"data": null}` rather than a 404. A 404 here means the schedule itself does not exist in this organization.

Requires scope config:read

Responses

200 application/json

The user on call, or null when nobody is

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No schedule with that ID in this organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

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

{
  "data": {
    "email": "noc@example.com",
    "id": "9d1a5c3e-1f2b-4c8a-9e7d-2b6f4a8c1d30"
  }
}

Puts one user on call for a fixed window, overriding whatever the rotation layers would otherwise resolve to. Attributes are nested under an `override` key; `schedule_id` is taken from the path and ignored in the body.

Requires scope config:write

Responses

201 application/json

The created override

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No schedule with that ID in this organization

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X POST https://staging.towerops.net/api/v1/schedules/$ID/overrides \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "override": {
    "end_time": "2026-01-15T19:44:25Z",
    "start_time": "2026-01-15T19:44:25Z",
    "user_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}'

{
  "data": {
    "accepted_at": "2026-01-15T19:44:25Z",
    "end_time": "2026-01-15T19:44:25Z",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "pending": true,
    "reason": "string",
    "requested_by": {
      "email": "noc@example.com",
      "id": "9d1a5c3e-1f2b-4c8a-9e7d-2b6f4a8c1d30"
    },
    "requested_by_id": "550e8400-e29b-41d4-a716-446655440000",
    "schedule_id": "550e8400-e29b-41d4-a716-446655440000",
    "start_time": "2026-01-15T19:44:25Z",
    "user": {
      "email": "noc@example.com",
      "id": "9d1a5c3e-1f2b-4c8a-9e7d-2b6f4a8c1d30"
    },
    "user_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Cancels an override; the rotation layers resolve the window again. The override must belong to the schedule named in the path, otherwise the request answers 404. Success is 200 with `{"data": {"deleted": true}}`.

Requires scope config:write

Responses

200 application/json

The override was deleted

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

The schedule or the override does not exist here

422 application/json

The override could not be deleted

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X DELETE https://staging.towerops.net/api/v1/schedules/$ID/overrides/$OVERRIDE_ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "deleted": true
  }
}

Lists every escalation policy in the authenticated organization. This endpoint does not paginate and omits `meta`; each entry carries the policy summary only, without its rules or their targets.

Requires scope config:read

Responses

200 application/json

Escalation policies

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

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

{
  "data": [
    {
      "alert_types": [
        "string"
      ],
      "check_types": [
        "string"
      ],
      "description": "string",
      "device_roles": [
        "string"
      ],
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "inserted_at": "2026-01-15T19:44:25Z",
      "minimum_severity": 1,
      "name": "string",
      "repeat_count": 0,
      "routing_order": 0,
      "site_ids": [
        "550e8400-e29b-41d4-a716-446655440000"
      ]
    }
  ]
}

Creates an escalation policy in the authenticated organization. The policy is created without rules: add them with the nested rule endpoints, then attach targets to each rule. `repeat_count` is the paging ceiling in hours: the chain loops its rules until `repeat_count` hours after the alert triggered, then stops paging and the alert shows "paging stopped". `minimum_severity`, `site_ids`, `device_roles`, `alert_types` and `check_types` scope which alerts the policy pages for. Severity is a floor (`1` warning, `2` critical; omit or `null` for any severity); sites must belong to this organization. Device roles include `router`, `switch`, `access_point`, `backhaul`, `server` and `other`. Alert types use persisted identifiers such as `agent_offline` or `check_http`; check types use the suffix of a `check_` alert type, such as `http`. All non-empty dimensions must match; values within a list are alternatives. Empty lists are unconstrained. Missing device/site context fails open only for site/role constraints: severity and type filters still apply. Scope identifiers are validated on write: every `alert_types` value must be an emitted alert class or a stored value already on the policy, and every `check_types` value a registered check type, anything else fails with `422` naming the offending values. To scope on a class the product does not emit (for example an SNMP trap rule's alert type), declare it in `custom_alert_types`, which merges into `alert_types` on save. There is no `custom_check_types`: every check alert carries a registry check type, so `check_types` is registry-only. An explicitly assigned device policy takes precedence, even when its scope refuses the alert. Otherwise, non-default policies with alert/check type filters are tried in ascending `routing_order` (nonnegative, default `0`), then creation time and ID; the first full-scope match wins. Existing non-default policies without type filters remain assignment-only. The organization default is the fallback, and its scope is still enforced.

Requires scope config:write

Responses

201 application/json

The created policy

400 application/json

The `escalation_policy` parameter is missing

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X POST https://staging.towerops.net/api/v1/escalation_policies \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "escalation_policy": {
    "alert_types": [
      "string"
    ],
    "check_types": [
      "string"
    ],
    "custom_alert_types": [
      "string"
    ],
    "description": "string",
    "device_roles": [
      "string"
    ],
    "handoff_notifications_mode": "when_in_use_by_service",
    "minimum_severity": 1,
    "name": "string",
    "repeat_count": 0,
    "routing_order": 0,
    "site_ids": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  }
}'

{
  "data": {
    "alert_types": [
      "string"
    ],
    "check_types": [
      "string"
    ],
    "description": "string",
    "device_roles": [
      "string"
    ],
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "minimum_severity": 1,
    "name": "string",
    "repeat_count": 0,
    "routing_order": 0,
    "site_ids": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  }
}

Gets one policy by ID. Unlike the list endpoint, this returns the full detail shape: every rule in `position` order with its notification targets nested underneath. Rules escalate in `position` order: a rule's targets are notified, and if the alert is still unacknowledged after that rule's `timeout_minutes` the next position is notified.

Requires scope config:read

Responses

200 application/json

The policy

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No policy with that ID in this organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl https://staging.towerops.net/api/v1/escalation_policies/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "alert_types": [
      "string"
    ],
    "check_types": [
      "string"
    ],
    "description": "string",
    "device_roles": [
      "string"
    ],
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "minimum_severity": 1,
    "name": "string",
    "repeat_count": 0,
    "routing_order": 0,
    "rules": [
      {
        "escalation_policy_id": "550e8400-e29b-41d4-a716-446655440000",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "inserted_at": "2026-01-15T19:44:25Z",
        "position": 0,
        "targets": [],
        "timeout_minutes": 0
      }
    ],
    "site_ids": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  }
}

Updates the given attributes of a policy. Omitted attributes are left alone. Rules and targets are not touched here; use the nested endpoints. The response is the summary shape, without rules. Scope and routing work as on create. Sending `[]` for `site_ids`, `device_roles`, `alert_types` or `check_types` clears that constraint; omitting it preserves its stored value. An explicit `minimum_severity: null` lowers the floor back to any severity. `routing_order: 0` restores the default order; omission preserves the stored order.

Requires scope config:write

Responses

200 application/json

The updated policy

400 application/json

The `escalation_policy` parameter is missing

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No policy with that ID in this organization

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X PATCH https://staging.towerops.net/api/v1/escalation_policies/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "escalation_policy": {
    "alert_types": [
      "string"
    ],
    "check_types": [
      "string"
    ],
    "custom_alert_types": [
      "string"
    ],
    "description": "string",
    "device_roles": [
      "string"
    ],
    "handoff_notifications_mode": "when_in_use_by_service",
    "minimum_severity": 1,
    "name": "string",
    "repeat_count": 0,
    "routing_order": 0,
    "site_ids": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  }
}'

{
  "data": {
    "alert_types": [
      "string"
    ],
    "check_types": [
      "string"
    ],
    "description": "string",
    "device_roles": [
      "string"
    ],
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "minimum_severity": 1,
    "name": "string",
    "repeat_count": 0,
    "routing_order": 0,
    "site_ids": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  }
}

Deletes a policy along with its rules and their targets.

Requires scope config:write

Responses

200 application/json

The policy was deleted

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No policy with that ID in this organization

422 application/json

The policy could not be deleted

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X DELETE https://staging.towerops.net/api/v1/escalation_policies/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "deleted": true
  }
}

Adds a rule (one escalation step) to a policy. Attributes are nested under a `rule` key; `escalation_policy_id` is taken from the path and ignored in the body. Rules fire in `position` order: the next position is notified once `timeout_minutes` elapses without the alert being acknowledged. A rule notifies nobody until targets are attached to it. Omit `position` to append the rule as the policy's last step. Supplying one places the rule at that step; a step another rule already uses answers 422, because steps are never renumbered (an in-flight escalation tracks the position it is on), move a rule with the update endpoint instead.

Requires scope config:write

Responses

201 application/json

The created rule

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No policy with that ID in this organization

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

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

{
  "data": {
    "escalation_policy_id": "550e8400-e29b-41d4-a716-446655440000",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "position": 0,
    "targets": [
      {
        "escalation_rule_id": "550e8400-e29b-41d4-a716-446655440000",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "inserted_at": "2026-01-15T19:44:25Z",
        "role": "string",
        "schedule_id": "550e8400-e29b-41d4-a716-446655440000",
        "target_type": "schedule",
        "user_id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "timeout_minutes": 0
  }
}

Updates a rule's `position` or `timeout_minutes`. Attributes are nested under a `rule` key; omitted attributes are left alone. The rule must belong to the policy named in the path, otherwise the request answers 404.

Requires scope config:write

Responses

200 application/json

The updated rule

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

The policy or the rule does not exist here

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X PATCH https://staging.towerops.net/api/v1/escalation_policies/$ID/rules/$RULE_ID \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "rule": {
    "position": 0,
    "timeout_minutes": 0
  }
}'

{
  "data": {
    "escalation_policy_id": "550e8400-e29b-41d4-a716-446655440000",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "position": 0,
    "targets": [
      {
        "escalation_rule_id": "550e8400-e29b-41d4-a716-446655440000",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "inserted_at": "2026-01-15T19:44:25Z",
        "role": "string",
        "schedule_id": "550e8400-e29b-41d4-a716-446655440000",
        "target_type": "schedule",
        "user_id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "timeout_minutes": 0
  }
}

Removes an escalation step from a policy along with its targets. The rule must belong to the policy named in the path, otherwise the request answers 404. Success is 200 with `{"data": {"deleted": true}}`, not 204.

Requires scope config:write

Responses

200 application/json

The rule was deleted

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

The policy or the rule does not exist here

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X DELETE https://staging.towerops.net/api/v1/escalation_policies/$ID/rules/$RULE_ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "deleted": true
  }
}

Attaches a notification target to a rule. Attributes are nested under a `target` key. `target_type` selects which id field is read: `user` reads `user_id`, `schedule` reads `schedule_id`, and `role` reads `role`. The referenced user or schedule must belong to the caller's organization; a cross-organization id is rejected with 422 rather than paging a stranger. For `target_type` `role`, `role` must be one of `owner`, `admin`, `executive`, `technician` or `viewer`, the retired `member` role is rejected with 422.

Requires scope config:write

Responses

201 application/json

The created target

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

The policy or the rule does not exist here

422 application/json

Validation failed, or the target does not name a user or schedule in this organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X POST https://staging.towerops.net/api/v1/escalation_policies/$ID/rules/$RULE_ID/targets \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "target": {
    "role": "owner",
    "schedule_id": "550e8400-e29b-41d4-a716-446655440000",
    "target_type": "schedule",
    "user_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}'

{
  "data": {
    "escalation_rule_id": "550e8400-e29b-41d4-a716-446655440000",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inserted_at": "2026-01-15T19:44:25Z",
    "role": "string",
    "schedule_id": "550e8400-e29b-41d4-a716-446655440000",
    "target_type": "schedule",
    "user_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Detaches a notification target from a rule. The whole chain is checked: the rule must belong to the policy and the target to the rule, otherwise the request answers 404. Success is 200 with `{"data": {"deleted": true}}`.

Requires scope config:write

Responses

200 application/json

The target was removed

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

The policy, rule or target does not exist here

422 application/json

The target could not be removed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X DELETE https://staging.towerops.net/api/v1/escalation_policies/$ID/rules/$RULE_ID/targets/$TARGET_ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "deleted": true
  }
}

Lists every outbound webhook endpoint in the authenticated organization. This endpoint does not paginate and omits `meta`. The signing `secret` is write-only: it is returned once, by `create`, and never appears here or on `show`/`update`.

Requires scope webhooks:manage

Responses

200 application/json

Webhook endpoints

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

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

{
  "data": [
    {
      "active": true,
      "consecutive_failures": 0,
      "events": [
        "alert.triggered",
        "alert.resolved"
      ],
      "id": "dd0e8400-e29b-41d4-a716-446655440007",
      "name": "NOC bus",
      "url": "https://hooks.example.com/towerops"
    }
  ]
}

Subscribes an HTTPS endpoint to organization events. `events` names the subscriptions; only those events are delivered to it. The catalog, with a description and an example payload per event, is `GET /api/v1/webhook_events`. This is the only response that carries `secret`, the key used for the `x-towerops-signature` header on every delivery. It is write-only afterwards: store it now, because no later read returns it.

Requires scope webhooks:manage

Responses

201 application/json

The created endpoint, including its signing secret

400 application/json

The `webhook_endpoint` parameter is missing

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X POST https://staging.towerops.net/api/v1/webhook_endpoints \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "webhook_endpoint": {
    "active": true,
    "events": [
      "string"
    ],
    "name": "string",
    "secret": "string",
    "url": "string"
  }
}'

{
  "data": {
    "active": true,
    "consecutive_failures": 0,
    "events": [
      "alert.triggered",
      "alert.resolved"
    ],
    "id": "dd0e8400-e29b-41d4-a716-446655440007",
    "name": "NOC bus",
    "secret": "string",
    "url": "https://hooks.example.com/towerops"
  }
}

Gets one endpoint by ID, including its delivery health: `consecutive_failures`, `last_delivery_at` and `last_delivery_status`. The signing secret is not returned.

Requires scope webhooks:manage

Responses

200 application/json

The endpoint

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No endpoint with that ID in this organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl https://staging.towerops.net/api/v1/webhook_endpoints/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "active": true,
    "consecutive_failures": 0,
    "events": [
      "alert.triggered",
      "alert.resolved"
    ],
    "id": "dd0e8400-e29b-41d4-a716-446655440007",
    "name": "NOC bus",
    "url": "https://hooks.example.com/towerops"
  }
}

Updates the given attributes of an endpoint. Omitted attributes are left alone, and `events` replaces the subscription list wholesale rather than merging with it. Setting `active` back to true is how an endpoint the circuit breaker deactivated is put back into service. A rotated `secret` may be sent here, but is never echoed back.

Requires scope webhooks:manage

Responses

200 application/json

The updated endpoint

400 application/json

The `webhook_endpoint` parameter is missing

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No endpoint with that ID in this organization

422 application/json

Validation failed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X PATCH https://staging.towerops.net/api/v1/webhook_endpoints/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "webhook_endpoint": {
    "active": true,
    "events": [
      "string"
    ],
    "name": "string",
    "secret": "string",
    "url": "string"
  }
}'

{
  "data": {
    "active": true,
    "consecutive_failures": 0,
    "events": [
      "alert.triggered",
      "alert.resolved"
    ],
    "id": "dd0e8400-e29b-41d4-a716-446655440007",
    "name": "NOC bus",
    "url": "https://hooks.example.com/towerops"
  }
}

Unsubscribes and removes an endpoint along with its delivery history.

Requires scope webhooks:manage

Responses

200 application/json

The endpoint was deleted

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No endpoint with that ID in this organization

422 application/json

The endpoint could not be deleted

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X DELETE https://staging.towerops.net/api/v1/webhook_endpoints/$ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "deleted": true
  }
}

Lists delivery attempts for one endpoint, newest first, paginated like every other collection: `page`/`per_page` (default 100, max 100) or the `?cursor=` returned under `meta.next_cursor`. Each entry carries the event name, the delivery status, the attempt count, the request payload sent, and the HTTP status, response body (truncated to 2000 characters) or transport error the receiver produced.

Requires scope webhooks:manage

Responses

200 application/json

Deliveries

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

No endpoint with that ID in this organization

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -G https://staging.towerops.net/api/v1/webhook_endpoints/$ID/deliveries \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-urlencode "cursor=VALUE" \
  --data-urlencode "page=VALUE" \
  --data-urlencode "per_page=VALUE"

{
  "data": [
    {
      "attempt_count": 0,
      "created_at": "2026-01-15T19:44:25Z",
      "delivered_at": "2026-01-15T19:44:25Z",
      "endpoint_id": "550e8400-e29b-41d4-a716-446655440000",
      "error": "string",
      "event": "string",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "last_attempt_at": "2026-01-15T19:44:25Z",
      "payload": null,
      "response_body": "string",
      "response_status": 0,
      "status": "string",
      "test": true
    }
  ],
  "meta": {
    "next_cursor": null,
    "page": 1,
    "per_page": 50,
    "total_count": 1,
    "total_pages": 1
  }
}

Re-sends a previously recorded delivery to its endpoint, the usual fix after a receiver outage. The replay is signed afresh and answers with the delivery's updated state; the response is 200, not 201. The delivery must belong to the endpoint named in the path: a delivery id that exists but belongs to another endpoint answers 404, exactly like an unknown id. A delivery that is still being attempted (queued, sending, or waiting to retry) answers 409 and is left alone; replay it once that attempt finishes.

Requires scope webhooks:manage

Responses

200 application/json

The replayed delivery

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

The endpoint does not exist here, or the delivery is not one of its own

409 application/json

The delivery is still being attempted

422 application/json

The delivery could not be replayed

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X POST https://staging.towerops.net/api/v1/webhook_endpoints/$ID/deliveries/$DELIVERY_ID/replay \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "attempt_count": 0,
    "created_at": "2026-01-15T19:44:25Z",
    "delivered_at": "2026-01-15T19:44:25Z",
    "endpoint_id": "550e8400-e29b-41d4-a716-446655440000",
    "error": "string",
    "event": "string",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "last_attempt_at": "2026-01-15T19:44:25Z",
    "payload": null,
    "response_body": "string",
    "response_status": 0,
    "status": "string",
    "test": true
  }
}

Queues a delivery built from the catalog's sample payload for `event` and returns its id. The worker sends it through the normal signed path, so the request carries the same `x-towerops-signature`, `x-towerops-timestamp` and `x-towerops-delivery` headers as a real delivery and lands in the delivery log with its real outcome. `event` must be one the endpoint is subscribed to. A test delivery never increments the endpoint's failure counter or trips its circuit breaker, and it delivers to a disabled endpoint the same way, that is what the test is for. Available while the send-test feature flag is enabled for the organization; otherwise the route answers 404.

Requires scope webhooks:manage

Responses

202 application/json

The queued delivery's id

400 application/json

The 'event' parameter is missing

401 application/json

Missing, malformed, expired or revoked credentials

403 application/json

The token is valid but lacks the scope this endpoint requires, or the resource belongs to another organization

404 application/json

The endpoint does not exist here, or the feature is not enabled

422 application/json

The event is unknown or the endpoint is not subscribed to it

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X POST https://staging.towerops.net/api/v1/webhook_endpoints/$ID/test \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "event": "string"
}'

{
  "delivery_id": "string"
}

Every event an endpoint can subscribe to, with when it fires and an example `data` payload. The same list validates `events` on create/update, renders the Settings → Webhooks picker and the Help → Webhooks section, and generates the catalog in `docs/features/webhooks.md`, so it cannot drift from what producers emit. The catalog is product metadata, not tenant data: any authenticated API token can read it, whatever its scopes. Creating, reading or changing endpoints still requires `webhooks:manage`.

Responses

200 application/json

Event catalog

401 application/json

Missing, malformed, expired or revoked credentials

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

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

{
  "data": [
    {
      "description": "string",
      "example": null,
      "name": "string",
      "payload_version": 0
    }
  ]
}

Inbound endpoint for CI to announce a new agent release, which broadcasts an update instruction to every connected agent. Two checks, both keyed on the same configured agent webhook secret and neither of them an API token. First, the route requires `Authorization: Bearer <agent webhook secret>`. Then this action requires an `x-agent-webhook-signature` header of the form `t=<unix>,v1=<hex>`, whose `v1` must be a constant-time match for a HMAC-SHA256 of `"<t>.<raw body>"`; a timestamp more than 300 seconds away from the server clock in either direction is refused so a captured request cannot be replayed (the same tolerance the Stripe webhook applies, a few seconds of CI clock skew are inside the window, not a rejection). A missing, repeated or unparseable signature header is a `401`, never a `500`. The request body is not read, it carries no fields, and the release to broadcast is resolved by the worker, but whatever bytes are sent are part of the signed payload. The broadcast is enqueued as a background job and acknowledged immediately. Rate limited to the webhook bucket, 300 requests per minute per caller IP, applied before the signature is checked.

Responses

200 application/json

The broadcast was enqueued: `{"data": {"status": "ok"}}`

401 application/json

The `Authorization` header is missing or does not carry the webhook secret, or the `x-agent-webhook-signature` header is absent, unparseable, outside the 300-second window or does not match

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

500 application/json

The background job could not be enqueued, or no agent webhook secret is configured on this deployment

curl -X POST https://staging.towerops.net/api/v1/webhooks/agent-release

{
  "data": {
    "status": "ok"
  }
}

Inbound endpoint for real-time subscriber and network updates from Gaiia. Verification uses the per-organization secret stored on the organization's `gaiia` integration: the `x-gaiia-webhook-signature` header is checked against a constant-time HMAC over the raw request body, with a 300-second replay window. Header parsing and the millisecond `t=` scale Gaiia stamps live in the Gaiia client library. The digest covers the raw bytes, so re-encoding the JSON invalidates it. No API token is used; the organization comes from the URL and the secret from its integration. The event is enqueued as a background job and acknowledged immediately, nothing in the response reflects the outcome of processing it. The event name is read from `eventName`, falling back to `event`. The payload is read from `payload`, falling back to `data`, and the entity ID from `objectId`, falling back to the payload's own `id`.

Responses

200 application/json

The event was accepted for background processing: `{"data": {"status": "ok"}}`

400 application/json

Neither `eventName` nor `event` is present in the body

401 application/json

The signature does not match, is outside the replay window, or the `x-gaiia-webhook-signature` header is absent, and, deliberately indistinguishably, the organization has no `gaiia` integration or no webhook secret configured on it

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

500 application/json

The background job could not be enqueued

curl -X POST https://staging.towerops.net/api/v1/webhooks/gaiia/$ORGANIZATION_ID

{
  "data": {
    "status": "ok"
  }
}

Raises or resolves an alert, appends an alert note, or records a device status for the organization. Authenticated by either an `x-towerops-signature`/`x-towerops-timestamp` HMAC over the raw body against the org's `inbound_alerts` integration `webhook_key`, or an API token (a superuser token works across organizations). Replaying a caller-supplied `event_id` is idempotent: the recorded outcome returns again and nothing re-acts.

Responses

202 application/json

Recorded outcome (`alert_id`, `note_id`, `device_id` or `status`)

400 application/json

Malformed event (`invalid_event`) or unresolvable target (`device_not_found`, `alert_not_found`)

401 application/json

All authentication failures are indistinguishable: bad or stale signature, missing or unknown org secret, invalid token, wrong-org token

403 application/json

A Bearer token without the write scope the event needs

404 application/json

The `inbound_alert_webhook` feature has no enabled gate for this caller

409 application/json

A `device_name` that matches more than one device (send `device_id`), or a duplicate `event_id` still being processed

422 application/json

The event's fields failed validation (e.g. an oversized note body)

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

curl -X POST https://staging.towerops.net/api/v1/webhooks/inbound/$ORGANIZATION_ID \
  -H "Content-Type: application/json" \
  -d '{
  "device_name": "site-42-ups",
  "event": "alert.raise",
  "event_id": "ups-7-site-42-20261029",
  "message": "Site 42 mains power lost",
  "severity": 1
}'

{
  "alert_id": "9f6d767f-e73d-47fe-9438-3bbb76e6ded7"
}

Inbound endpoint for a MikroTik router's DHCP lease script. Authentication is the per-organization shared secret stored on the organization's `mikrotik` integration, presented in the `X-TowerOps-Token` header and compared in constant time. There is no signature and no API token. `bound` is required and is sent by the router as a string: `"1"` records an assignment, `"0"` a release, and anything else is rejected. `bound` and every other parameter are forwarded to the worker as the payload. The event is enqueued and acknowledged immediately so the router's `/tool fetch` does not block the lease state machine. Identical to the `pppoe` endpoint apart from the source it records, `dhcp` here, `pppoe` there.

Responses

200 application/json

The event was accepted for background processing: `{"data": {"status": "ok"}}`

400 application/json

`bound` is missing or is neither `"1"` nor `"0"`

401 application/json

The `X-TowerOps-Token` header is absent or does not match the integration's token, and, deliberately indistinguishably, the organization has no `mikrotik` integration, has it disabled, or has no webhook token configured on it

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

500 application/json

The background job could not be enqueued

curl -X POST https://staging.towerops.net/api/v1/webhooks/mikrotik/$ORGANIZATION_ID/dhcp

{
  "data": {
    "status": "ok"
  }
}

Inbound endpoint for a MikroTik router's PPPoE on-up and on-down scripts. Authentication is the per-organization shared secret stored on the organization's `mikrotik` integration, presented in the `X-TowerOps-Token` header and compared in constant time. There is no signature and no API token. `bound` is required and is sent by the router as a string: `"1"` records an assignment, `"0"` a release, and anything else is rejected. `bound` and every other parameter are forwarded to the worker as the payload. The event is enqueued and acknowledged immediately so the router's `/tool fetch` does not block the PPP state machine. Identical to the `dhcp` endpoint apart from the source it records, `pppoe` here, `dhcp` there.

Responses

200 application/json

The event was accepted for background processing: `{"data": {"status": "ok"}}`

400 application/json

`bound` is missing or is neither `"1"` nor `"0"`

401 application/json

The `X-TowerOps-Token` header is absent or does not match the integration's token, and, deliberately indistinguishably, the organization has no `mikrotik` integration, has it disabled, or has no webhook token configured on it

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

500 application/json

The background job could not be enqueued

curl -X POST https://staging.towerops.net/api/v1/webhooks/mikrotik/$ORGANIZATION_ID/pppoe

{
  "data": {
    "status": "ok"
  }
}

Inbound endpoint for PagerDuty V3 webhook events, which is how an incident acknowledged or resolved in PagerDuty is reflected back onto the TowerOps alert. Verification uses the per-organization signature secret stored on the organization's enabled `pagerduty` integration: every `v1=<hex>` value in the `x-pagerduty-signature` header (the header may carry several, comma-separated, during secret rotation) is compared in constant time against a HMAC-SHA256 of the raw request body. The integration's own organization must also match the one in the URL. The digest covers the raw bytes, so re-encoding the JSON invalidates it. No API token is used. The event is enqueued as a background job and acknowledged immediately, nothing in the response reflects the outcome of processing it. Only `incident.resolved` and `incident.acknowledged` are acted on. Any other `event.event_type`, and a body without `event.event_type` and `event.data`, is still answered `200 accepted` and dropped, so PagerDuty does not retry events this integration has no use for.

Responses

200 application/json

The event was accepted for background processing, or recognised and deliberately ignored: `{"data": {"status": "accepted"}}`

400 application/json

The request had no body to verify a signature over

401 application/json

No `x-pagerduty-signature` value matches the HMAC of the body, and, deliberately indistinguishably, the organization has no enabled `pagerduty` integration, no webhook secret configured on it, or the integration belongs to a different organization than the URL names

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

500 application/json

The background job could not be enqueued

curl -X POST https://staging.towerops.net/api/v1/webhooks/pagerduty/$ORGANIZATION_ID

{
  "data": {
    "status": "ok"
  }
}

Quo sends version 2026-03-30 deliveries here after provisioning through Organization Settings. HMAC-SHA256 covers webhook-id.webhook-timestamp.raw-body; webhook-signature contains space-separated v1 base64 candidates. The per-org whsec_ key is base64-decoded before verification. Timestamps must be within 300 seconds in either direction. Only enabled integrations accept delivery. Incoming message.received, call.completed and call.voicemail.completed events are queued; other event types are acknowledged without capture. Delivery ids are idempotent per organization. No API token is used.

Responses

200 application/json

Accepted for asynchronous processing

400 application/json

Malformed event

401 application/json

Webhook verification failed (all verification failures are indistinguishable)

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

500 application/json

Failed to enqueue

curl -X POST https://staging.towerops.net/api/v1/webhooks/quo/$ORGANIZATION_ID

{
  "data": {
    "status": "ok"
  }
}

Slack sends application/x-www-form-urlencoded block_actions or /towerops status. The v0 HMAC covers the exact raw body and timestamp (within 300 seconds). Valid requests are queued before Slack's three-second deadline; completion is sent privately with chat.postEphemeral, never to a supplied response_url. Workspace membership and action permission are checked again during processing.

Responses

200 application/json

Ephemeral acknowledgement

401 application/json

Invalid signature

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

503 application/json

Queue unavailable

curl -X POST https://staging.towerops.net/api/v1/webhooks/slack

{
  "data": {
    "status": "ok"
  }
}

Inbound endpoint for Stripe billing events. Verification is a HMAC-SHA256 over the raw request body, keyed on the configured Stripe webhook secret and read from the `stripe-signature` header (`t=<unix>,v1=<hex>[,v1=<hex>…]`; a secret rotation makes Stripe send several `v1` values), every candidate is compared in constant time and any match accepts the request. The timestamp must be within 300 seconds, so a captured request cannot be replayed later. The signature covers the raw bytes: re-encoding the JSON invalidates it. No API token is used. The event is enqueued as a background job and acknowledged immediately, nothing in the response reflects the outcome of processing it. The body is the Stripe event object as Stripe sends it and is forwarded to the worker unchanged.

Responses

200 application/json

The event was accepted for background processing: `{"data": {"received": true}}`

400 application/json

The body is not valid JSON, or the `stripe-signature` header is missing, unparseable or outside the 300-second tolerance

401 application/json

The signature does not match the webhook secret

429 application/json

Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header

500 application/json

The background job could not be enqueued

curl -X POST https://staging.towerops.net/api/v1/webhooks/stripe

{
  "data": {
    "status": "ok"
  }
}

Gets one alert by ID, in the same shape `list_alerts` rows carry, including `site_id`, `site_name`, `subscriber_impact` and `assigned_to_email`. This is the deep-link target a push notification's `alert_id` resolves against. An alert outside the session's organizations, or at a site outside the member's site restriction, answers 404 rather than 403 so the id's existence is never confirmed, the same rule `get_device` applies.

Responses

200 application/json

The alert

401 application/json

The bearer token is missing, malformed, expired or revoked

404 application/json

No alert with that ID, or the alert belongs to an organization or site outside the session's access: `Alert not found`

429 application/json

Rate limit exceeded (1000/min API bucket)

curl https://staging.towerops.net/api/v1/mobile/alerts/$ID \
  -H "Authorization: Bearer MOBILE_SESSION_TOKEN"

{
  "alert_type": "string",
  "assigned_to_email": "string",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "string",
  "site_id": "550e8400-e29b-41d4-a716-446655440000",
  "site_name": "string",
  "subscriber_impact": null,
  "triggered_at": "2026-01-15T19:44:25Z"
}

Acknowledges the alert for the session's user, attributed the same way the web action bar and the REST acknowledge record it. Gated on `:field_brief`; an alert outside the caller's organization or site restriction answers 404.

Responses

200 application/json

The acknowledged alert

401 application/json

The bearer token is missing, malformed, expired or revoked

404 application/json

No such alert, or :field_brief is off for this caller

429 application/json

Rate limit exceeded (1000/min API bucket)

curl -X POST https://staging.towerops.net/api/v1/mobile/alerts/$ID/acknowledge \
  -H "Authorization: Bearer MOBILE_SESSION_TOKEN"

{
  "alert_type": "string",
  "assigned_to_email": "string",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "string",
  "site_id": "550e8400-e29b-41d4-a716-446655440000",
  "site_name": "string",
  "subscriber_impact": null,
  "triggered_at": "2026-01-15T19:44:25Z"
}

Appends an operator note to the alert's thread, attributed to the session's user; it appears in the web timeline immediately. Gated on `:field_brief`; an alert outside the caller's organization or site restriction answers 404. The body is `{"note": {"body": "..."}}`, the same shape the REST note endpoint takes.

Responses

201 application/json

The stored note

401 application/json

The bearer token is missing, malformed, expired or revoked

404 application/json

No such alert, or :field_brief is off for this caller

422 application/json

A non-empty `note.body` string is required

429 application/json

Rate limit exceeded (1000/min API bucket)

curl -X POST https://staging.towerops.net/api/v1/mobile/alerts/$ID/notes \
  -H "Authorization: Bearer MOBILE_SESSION_TOKEN"

{
  "author_email": "string",
  "body": "string",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "inserted_at": "2026-01-15T19:44:25Z"
}

Permanently deletes the signed-in user's account. App Store guideline 5.1.1(v) requires this from inside the app, so it cannot live only in the web settings page. Send `password` when the account has one and `confirmation_code` when it does not, `GET /api/v1/mobile/auth/session` reports which through `password_required`, and `POST /api/v1/mobile/auth/account/confirmation` emails the code. An account with TOTP enrolled must also send `totp_code`; the session reports that through `totp_required`. `delete_organizations` (default `false`) is the way out for the last owner of an organization who has nobody to hand it to; it destroys every site, device, alert and other member's access along with it. Every refusal is a machine-readable code rather than prose, so the app can branch: it reveals its password field on `invalid_password`, which is how a client holding a stale `password_required` recovers. A wrong credential answers `403`, never `401`, the app signs itself out on any `401`, so a typo would otherwise log the user out. The `409` bodies also carry `organizations`, the names the app shows before asking again. Deleting the user cascades to this mobile session, so there is nothing left to revoke afterwards. Rate limited to the 10/min auth bucket, not the API one, because it is a credential check.

Responses

200 application/json

The account was deleted: `{"success": true}`

401 application/json

The bearer token is missing, malformed, expired or revoked. Credential failures answer `403`, not this

403 application/json

`invalid_password`, `confirmation_code_required`, `invalid_confirmation_code`, `totp_code_required` or `invalid_totp_code`

409 application/json

`sole_owner` or `active_subscription`, each with the blocking organization names under `organizations`

429 application/json

Rate limit exceeded (10/min auth bucket)

curl -X DELETE https://staging.towerops.net/api/v1/mobile/auth/account \
  -H "Authorization: Bearer MOBILE_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "confirmation_code": "string",
  "delete_organizations": true,
  "password": "string",
  "totp_code": "string"
}'

{
  "sent": true,
  "success": true
}

Emails a short confirmation code for deleting an account that has no password, for use as `confirmation_code` on `DELETE /api/v1/mobile/auth/account`. Takes no body. Only valid for a passwordless account: one with a password is challenged with that instead and answers `409 password_required` rather than sending a code that would never be checked. `{"sent": true}` is what tells the app to stop offering to send and start asking for the code, so a queue failure is reported as `500 could_not_send_code` rather than a success, otherwise someone waits for mail that is never coming with no way back. Rate limited to the 10/min auth bucket.

Responses

200 application/json

The code was emailed: `{"sent": true}`

401 application/json

The bearer token is missing, malformed, expired or revoked

409 application/json

The account has a password and must be challenged with it: `password_required`

429 application/json

Rate limit exceeded (10/min auth bucket)

500 application/json

The code could not be queued for delivery: `could_not_send_code`