towerops/docs/terraform-coverages.md

Coverages over the Towerops API (Terraform-friendly)

Towerops exposes a resourceful REST API for RF coverage predictions that's stable enough to drive from Terraform, Ansible, or any infrastructure-as-code tool. All endpoints live under /api/v1/ and use Bearer-token auth scoped to a single organization.

Looking for an Ansible-native interface? The official Towerops Ansible collection wraps these endpoints with idempotent modules: https://codeberg.org/towerops/ansible.

Authentication

Mint a token from Settings → API tokens. Send it as:

Authorization: Bearer towerops_<token>

The token is org-scoped — every endpoint reads/writes inside that org only.

Resources

Method	Path	Purpose
GET	/api/v1/coverages	List all coverages in the org.
POST	/api/v1/coverages	Create a coverage. The compute pipeline is queued automatically.
GET	/api/v1/coverages/:id	Read a single coverage including current status / progress_pct.
PATCH	/api/v1/coverages/:id	Update editable fields (does not auto-recompute).
DELETE	/api/v1/coverages/:id	Delete a coverage and its on-disk rasters.
POST	/api/v1/coverages/:id/recompute	Re-run the compute pipeline. Returns 202 with status: "queued".
GET	/api/v1/coverages/:id/kmz	Download a KMZ overlay for Google Earth (returns 409 until status: "ready").

Create payload

{
  "coverage": {
    "name": "North sector 5 GHz",
    "site_id": "1f4...uuid",
    "antenna_slug": "rf-elements-twistport-symmetrical-horn-30",
    "frequency_ghz": 5.8,
    "tx_power_dbm": 22.0,
    "height_agl_ft": 100,
    "azimuth_deg": 0,
    "downtilt_deg": 0,
    "radius_mi": 4
  }
}

Imperial inputs are accepted via the virtual fields shown above; the schema converts them to SI before validation.

Polling for :ready

Compute is asynchronous. After POST you'll receive status: "queued"; the worker transitions through "computing" to "ready" (or "failed"). Terraform providers can poll with GET /api/v1/coverages/:id until status == "ready" before declaring the resource healthy.

Terraform example

A Terraform provider for Towerops isn't published yet, but a hand-rolled restapi provider works today:

terraform {
  required_providers {
    restapi = { source = "Mastercard/restapi", version = "~> 1.18" }
  }
}

provider "restapi" {
  uri                  = "https://app.towerops.com"
  write_returns_object = true
  headers = {
    Authorization = "Bearer ${var.towerops_token}"
    Content-Type  = "application/json"
  }
}

resource "restapi_object" "north_sector" {
  path         = "/api/v1/coverages"
  id_attribute = "id"

  data = jsonencode({
    coverage = {
      name           = "North sector 5 GHz"
      site_id        = var.site_id
      antenna_slug   = "rf-elements-twistport-symmetrical-horn-30"
      frequency_ghz  = 5.8
      tx_power_dbm   = 22.0
      height_agl_ft  = 100
      azimuth_deg    = 0
      downtilt_deg   = 0
      radius_mi      = 4
    }
  })
}

terraform apply creates the coverage; terraform destroy deletes it. Updates flow through PATCH. Use terraform_data + a provisioner if you need to wait on status = "ready" before proceeding.