{
  "openapi": "3.2.0",
  "info": {
    "title": "Phone Home REST API",
    "version": "2.2.0",
    "description": "REST API for Phone Home device management, reseller-scoped Order Entry, and warehouse execution."
  },
  "servers": [{"url": "/"}],
  "components": {
    "securitySchemes": {
      "BearerAuth": {"type": "http", "scheme": "bearer"}
    },
    "parameters": {
      "RequestID": {"name": "X-Request-ID", "in": "header", "required": false, "schema": {"type": "string"}},
      "IdempotencyKey": {"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string"}}
    },
    "schemas": {
      "AcceptedTask": {"type": "object", "properties": {"status": {"type": "string", "example": "accepted"}, "mac_addr": {"type": "string"}, "task_id": {"type": "string"}}},
      "SSIDPatch": {"type": "object", "properties": {"idempotency_key": {"type": "string"}, "name": {"type": "string", "maxLength": 32}, "password": {"type": "string", "minLength": 8, "maxLength": 63}, "psk": {"type": "string", "deprecated": true}, "enabled": {"type": "boolean"}, "active": {"type": "boolean", "deprecated": true}, "wifi_security_mode": {"type": "string", "enum": ["open", "wpa-wpa2-psk", "wpa2-psk", "wpa3-sae", "wpa2-psk/wpa3-sae"]}, "encryption_type": {"type": "string", "deprecated": true}, "hidden": {"type": "boolean"}, "random_bssid": {"type": "boolean"}, "custom_dns_server_1": {"type": ["string", "null"]}, "custom_dns_server_2": {"type": ["string", "null"]}, "captive_portal_enabled": {"type": "boolean", "description": "Guest Wi-Fi only. Enabling requires enabled=true and open security."}, "band": {"type": "string", "enum": ["all", "2.4 only", "5 only"]}}},
      "WiFiNetworkConfig": {"type": "object", "properties": {"enabled": {"type": "boolean"}, "name": {"type": "string"}, "password": {"type": ["string", "null"], "description": "Current configured password; null for open Wi-Fi."}, "wifi_security_mode": {"type": "string"}, "bands_in_sync": {"type": "boolean"}, "captive_portal_enabled": {"type": "boolean"}}},
      "WiFiConfig": {"type": "object", "properties": {"mac_addr": {"type": "string"}, "wifi": {"type": "object", "properties": {"private": {"$ref": "#/components/schemas/WiFiNetworkConfig"}, "guest": {"$ref": "#/components/schemas/WiFiNetworkConfig"}}}}},
      "NetworkInterfaceConfig": {"type": "object", "required": ["name", "priority"], "properties": {"name": {"type": "string", "enum": ["cellular1", "ethernet1", "ethernet2"]}, "priority": {"type": "integer", "minimum": 1}}},
      "NetworkSettings": {"type": "object", "required": ["interfaces", "preferred_sim", "sim1_apn", "sim2_apn"], "properties": {"mac_addr": {"type": "string"}, "interfaces": {"type": "array", "items": {"$ref": "#/components/schemas/NetworkInterfaceConfig"}}, "preferred_sim": {"type": "string", "enum": ["1", "2"]}, "sim_auto_switch_enabled": {"type": "boolean", "description": "Returned after the device reports native auto-switch support."}, "sim_auto_switch_pending": {"type": "boolean", "description": "True while an auto-switch change awaits device apply. Otherwise omitted."}, "sim1_apn": {"type": "string", "maxLength": 128}, "sim2_apn": {"type": "string", "maxLength": 128}}},
      "NetworkSettingsPatch": {"type": "object", "required": ["interface_order", "preferred_sim", "sim1_apn", "sim2_apn"], "properties": {"idempotency_key": {"type": "string", "maxLength": 40}, "interface_order": {"type": "array", "uniqueItems": true, "items": {"type": "string", "enum": ["cellular1", "ethernet1", "ethernet2"]}}, "preferred_sim": {"type": "string", "enum": ["1", "2"]}, "sim_auto_switch_enabled": {"type": "boolean", "description": "Omit to keep the current SIM auto-switch setting."}, "preserve_active_sim": {"type": "boolean", "description": "With auto-switch enabled, confirm preferred_sim is the live modem slot before applying."}, "sim1_apn": {"type": "string", "maxLength": 128}, "sim2_apn": {"type": "string", "maxLength": 128}}},
      "SignalTestRequest": {"type": "object", "required": ["server_ip", "interface"], "properties": {"idempotency_key": {"type": "string"}, "server_ip": {"type": "string", "format": "ipv4"}, "interface": {"type": "string", "description": "One of the interfaces currently reported as available by the device heartbeat."}, "collect_metrics": {"type": "boolean", "default": true}, "collect_bandwidth": {"type": "boolean", "default": true}, "collect_jitter_packet_loss": {"type": "boolean", "default": true}, "bandwidth_seconds": {"type": "integer", "minimum": 1, "default": 30}, "jitter_packet_loss_seconds": {"type": "integer", "minimum": 1, "default": 10}}},
      "LiveSignalTestRequest": {"type": "object", "required": ["idempotency_key", "server_ip", "interface", "interval_seconds", "max_duration_seconds"], "properties": {"idempotency_key": {"type": "string"}, "server_ip": {"type": "string", "format": "ipv4"}, "interface": {"type": "string", "description": "One of the interfaces currently reported as available by the device heartbeat."}, "interval_seconds": {"type": "integer", "enum": [10]}, "max_duration_seconds": {"type": "integer", "minimum": 60, "maximum": 3600, "description": "Hard device-side safety ceiling. Dashboard renewal windows remain part of the same session."}}},
      "LiveSignalTestStopRequest": {"type": "object", "required": ["idempotency_key"], "properties": {"idempotency_key": {"type": "string"}}},
      "EnhancedSiteHealth": {"type": "object", "required": ["status", "stale", "interfaces"], "properties": {"status": {"type": "string"}, "observed_at": {"type": "string", "format": "date-time"}, "stale": {"type": "boolean"}, "interfaces": {"type": "array", "maxItems": 2, "items": {"type": "object", "required": ["interface", "role", "server_ip", "status"], "properties": {"interface": {"type": "string"}, "role": {"type": "string", "enum": ["primary", "standby"]}, "server_ip": {"type": "string", "format": "ipv4"}, "status": {"type": "string", "enum": ["healthy", "degraded", "down", "unknown"]}, "score": {"type": "integer", "minimum": 0, "maximum": 100}, "latency_ms": {"type": "number"}, "packet_loss_percent": {"type": "number", "minimum": 0, "maximum": 100}, "error": {"type": "string"}}}}}},
      "SignalTestComparisonRequest": {"type": "object", "required": ["server_ip"], "properties": {"idempotency_key": {"type": "string"}, "server_ip": {"type": "string", "format": "ipv4"}, "collect_metrics": {"type": "boolean", "default": true}, "collect_bandwidth": {"type": "boolean", "default": true}, "collect_jitter_packet_loss": {"type": "boolean", "default": true}, "bandwidth_seconds": {"type": "integer", "minimum": 1, "default": 30}, "jitter_packet_loss_seconds": {"type": "integer", "minimum": 1, "default": 10}}},
      "RestartRequest": {"type": "object", "properties": {"idempotency_key": {"type": "string"}}},
      "FirmwareUpdateRequest": {"type": "object", "required": ["firmware_version"], "properties": {"idempotency_key": {"type": "string"}, "firmware_version": {"type": "string", "enum": ["4.8.3"]}}},
      "CLICommandRequest": {"type": "object", "required": ["command"], "properties": {"idempotency_key": {"type": "string"}, "command": {"type": "string"}, "timeout_sec": {"type": "integer", "minimum": 1}, "max_output_bytes": {"type": "integer", "minimum": 1, "maximum": 65535}}},
      "CreateDeviceRequest": {
        "type": "object",
        "required": ["mac_addr", "model_id"],
        "example": {
          "mac_addr": "02:11:22:33:44:55",
          "model_id": 1,
          "sn": "K500-000123",
          "target_firmware": "4.8.3",
          "target_phone_home_version": "v3",
          "interval_sitehealth": 300,
          "interval_heartbeat": 10,
          "interval_watcher_sync": 86400,
          "autossh_enabled": true,
          "confirm_regenerate_security_keys": false,
          "security_keys": {"autossh_key": "ssh-ed25519 AAAA..."},
          "passwords": [{"user": "root", "password": "StrongPassword2026"}],
          "config": {"guest_2g_ssid": "some ssid for guests"}
        },
        "properties": {
          "mac_addr": {"type": "string"},
          "model_id": {"type": "integer"},
          "sn": {"type": "string"},
          "target_firmware": {"type": "string", "enum": ["4.8.3"], "default": "4.8.3"},
          "target_phone_home_version": {"type": "string", "description": "Must be a version returned for the agent package by GET /v1/devops/phone-home-versions. Defaults to the newest returned version."},
          "interval_sitehealth": {"type": "integer", "description": "Optional; omitted values use the database default."},
          "interval_heartbeat": {"type": "integer", "description": "Optional; omitted values use the database default."},
          "interval_watcher_sync": {"type": "integer", "description": "Optional; omitted values use the database default."},
          "autossh_enabled": {"type": "boolean", "description": "Optional; omitted values use the database default."},
          "confirm_regenerate_security_keys": {"type": "boolean", "default": false, "description": "Required as true to regenerate Phone Home keys for an existing MAC. The device key files must be updated after regeneration."},
          "security_keys": {
            "type": "object",
            "description": "Phone Home keys are generated automatically when omitted. Advanced callers may provide a complete key set; partial key sets are rejected.",
            "properties": {
              "server_public_send_key": {"type": "string", "description": "Generated server_x25519_public.b64 value."},
              "server_private_receive_key": {"type": "string", "description": "Generated server_x25519_private.b64 value."},
              "device_public_signing_key_ed25519": {"type": "string", "description": "Generated client_ed25519_public.b64 value."},
              "device_public_encryption_key_x25519": {"type": "string", "description": "Generated client_x25519_public.b64 value."},
              "device_private_signing_key_ed25519": {"type": "string", "description": "Generated client_ed25519_private.b64 value."},
              "device_private_encryption_key_x25519": {"type": "string", "description": "Generated client_x25519_private.b64 value."},
              "autossh_key": {"type": "string"}
            }
          },
          "passwords": {"type": "array", "items": {"type": "object", "required": ["password"], "properties": {"user": {"type": "string"}, "password": {"type": "string", "minLength": 14}}}},
          "config": {"type": "object", "description": "Initial config overrides applied over default_config_template.json. Keys may be flat config table fields, for example guest_2g_ssid. Firewall rules and DHCP reservations are managed through separate devops tables."}
        }
      },
      "CreateDeviceResponse": {"type": "object", "properties": {"status": {"type": "string", "example": "created"}, "mac_addr": {"type": "string"}, "autossh_ssh_port_id": {"type": "integer"}, "autossh_web_port_id": {"type": "integer"}, "autossh_luci_port_id": {"type": "integer"}, "config_id": {"type": "integer"}, "password_count": {"type": "integer"}}},
      "PasswordRecord": {"type": "object", "properties": {"id": {"type": "integer"}, "mac": {"type": "string"}, "version": {"type": "integer"}, "active": {"type": "boolean"}, "user": {"type": "string"}, "password": {"type": "string", "description": "Sensitive plaintext device password; devops access only."}, "ts": {"type": "string"}, "ts_user": {"type": "string"}}},
      "DeviceDetails": {"type": "object", "properties": {"device": {"type": "object"}, "latest_config": {"type": "object"}, "config_deployment": {"type": "object"}, "config_lan_interfaces": {"type": "array", "items": {"type": "object"}}, "config_wifi_networks": {"type": "array", "items": {"type": "object"}}, "config_captive_portals": {"type": "array", "items": {"type": "object"}}, "config_sim": {"type": "object"}, "config_sim_band_lock": {"type": "object"}, "config_sim_bands": {"type": "array", "items": {"type": "object"}}, "config_sim_tower_lock": {"type": "object"}, "config_firewall_rules": {"type": "array", "items": {"type": "object"}}, "config_ports": {"type": "array", "items": {"type": "object"}}, "config_multiwan": {"type": "object"}, "config_multiwan_interfaces": {"type": "array", "items": {"type": "object"}}, "config_compiled": {"type": "object"}, "config_dhcp_reservations": {"type": "array", "items": {"type": "object"}}, "passwords": {"type": "array", "items": {"$ref": "#/components/schemas/PasswordRecord"}}, "security_keys_ready": {"type": "boolean", "description": "True only when the device has a security_keys row and every key field is non-null."}, "firewall_rules": {"type": "array", "deprecated": true, "items": {"type": "object"}}, "dhcp_reservations": {"type": "array", "deprecated": true, "items": {"type": "object"}}, "recent_tasks": {"type": "array", "items": {"type": "object"}}, "signal_tests": {"type": "array", "items": {"type": "object"}}, "signal_test_interfaces": {"type": "array", "description": "Latest heartbeat-reported interfaces available for signal testing, active first.", "items": {"type": "object", "properties": {"name": {"type": "string"}, "active": {"type": "boolean"}, "observed_at": {"type": "string", "format": "date-time"}}}}, "firmware_builds": {"type": "array", "description": "Global-admin-only firmware build history; omitted for other devops users.", "items": {"type": "object"}}}},
      "CreateRootPasswordResponse": {"type": "object", "properties": {"status": {"type": "string", "example": "created"}, "password": {"$ref": "#/components/schemas/PasswordRecord"}}},
      "PhoneHomeVersions": {"type": "object", "properties": {"package": {"type": "string", "example": "agent"}, "versions": {"type": "array", "description": "Artifact Registry agent versions ordered newest to oldest.", "items": {"type": "string"}}}},
      "DeviceVersionsPatch": {"type": "object", "minProperties": 1, "properties": {"target_firmware": {"type": "string", "enum": ["4.8.3"]}, "target_phone_home_version": {"type": "string", "description": "Must be present in the current Artifact Registry agent version list."}}},
      "ProviderSessionRequest": {"type": "object", "required": ["provider"], "properties": {"provider": {"type": "string", "enum": ["google_workspace", "workos"]}, "credential": {"type": "string", "description": "Google ID token validated for the configured OAuth client audience; Google only."}, "authorization_code": {"type": "string", "description": "WorkOS authorization code; WorkOS only."}, "code_verifier": {"type": "string", "description": "PKCE verifier; WorkOS only."}}},
      "SessionProfile": {"type": "object", "properties": {"web_user_id": {"type": "integer"}, "name": {"type": "string"}, "display_name": {"type": "string"}, "channel_id": {"type": ["integer", "null"]}, "channel_name": {"type": "string"}, "global_scope": {"type": "boolean"}, "roles": {"type": "array", "items": {"type": "string"}}, "permissions": {"type": "array", "items": {"type": "string"}}, "auth_provider": {"type": "string"}, "provider_organization_id": {"type": "string"}, "provider_expires_at": {"type": ["string", "null"], "format": "date-time"}, "session_expires_at": {"type": "string", "format": "date-time"}}},
      "Channel": {"type": "object", "properties": {"id": {"type": "integer"}, "code": {"type": "string"}, "name": {"type": "string"}, "workos_organization_id": {"type": "string"}, "cloud1_reseller_id": {"type": ["integer", "null"]}, "is_colony_master": {"type": "boolean"}, "active": {"type": "boolean"}}},
      "Company": {"type": "object", "properties": {"id": {"type": "string", "format": "uuid"}, "channel_id": {"type": "integer"}, "status": {"type": "string"}, "local_identifier": {"type": "string"}, "name": {"type": "string"}, "cloud1_company_id": {"type": ["integer", "null"]}}},
      "Site": {"type": "object", "properties": {"id": {"type": "string", "format": "uuid"}, "channel_id": {"type": "integer"}, "company_id": {"type": "string", "format": "uuid"}, "status": {"type": "string"}, "local_identifier": {"type": "string"}, "name": {"type": "string"}, "cloud1_site_id": {"type": ["integer", "null"]}}},
      "Product": {"type": "object", "properties": {"id": {"type": "string", "format": "uuid"}, "product_code": {"type": "string"}, "name": {"type": "string"}, "description": {"type": "string"}, "active": {"type": "boolean"}, "skus": {"type": "array", "description": "Colony catalog administration only; immutable Order-line component snapshots preserve historical composition.", "items": {"type": "object", "properties": {"sku_id": {"type": "string", "format": "uuid"}, "sku_code": {"type": "string"}, "quantity": {"type": "integer", "minimum": 1}}}}}},
      "SKU": {"type": "object", "properties": {"id": {"type": "string", "format": "uuid"}, "sku_code": {"type": "string"}, "name": {"type": "string"}, "serialized": {"type": "boolean"}, "unit_of_measure": {"type": "string"}, "cloud1_product": {"type": "boolean"}, "cloud1_product_id": {"type": ["integer", "null"], "minimum": 1}, "active": {"type": "boolean"}}},
      "Order": {"type": "object", "properties": {"id": {"type": "string", "format": "uuid"}, "order_number": {"type": "string"}, "channel_id": {"type": "integer"}, "customer_company_id": {"type": "string", "format": "uuid"}, "status": {"type": "string", "enum": ["draft", "submitted", "accepted", "held", "released", "partially_shipped", "shipped", "completed", "cancelled", "archived"]}, "source": {"type": "string"}, "total_quantity": {"type": "integer"}}},
      "BatchComponent": {"type": "object", "properties": {"id": {"type": "string", "format": "uuid", "description": "Immutable Order-line component snapshot ID."}, "sku_id": {"type": "string", "format": "uuid"}, "sku_code": {"type": "string"}, "sku_name": {"type": "string"}, "quantity_per_product": {"type": "integer", "minimum": 1}, "required_quantity": {"type": "integer"}, "assigned_quantity": {"type": "integer"}}},
      "FulfillmentGroupItem": {"type": "object", "description": "Raw physical SKU quantity from one Product allocation assigned to one Batch service site.", "properties": {"id": {"type": "string", "format": "uuid"}, "batch_allocation_id": {"type": "string", "format": "uuid"}, "order_line_component_id": {"type": "string", "format": "uuid"}, "order_line_id": {"type": "string", "format": "uuid"}, "order_number": {"type": "string"}, "product_code": {"type": "string"}, "sku_id": {"type": "string", "format": "uuid"}, "sku_code": {"type": "string"}, "sku_name": {"type": "string"}, "quantity": {"type": "integer", "minimum": 1}}},
      "FulfillmentGroup": {"type": "object", "description": "One service site in the site-first Batch plan. Shipping defaults to the service site.", "properties": {"id": {"type": "string", "format": "uuid"}, "group_number": {"type": "integer"}, "service_site_id": {"type": "string", "format": "uuid"}, "service_site_name": {"type": "string"}, "service_site_ready": {"type": "boolean"}, "destination_site_id": {"type": ["string", "null"], "format": "uuid"}, "destination_site_name": {"type": "string"}, "destination_site_ready": {"type": "boolean"}, "ship_to": {"type": "object"}, "requested_ship_date": {"type": "string", "format": "date"}, "requested_delivery_date": {"type": "string", "format": "date"}, "installation_mode": {"type": "string", "enum": ["self_install", "installer"]}, "installer_payer": {"type": ["string", "null"], "enum": ["client", "colony", "reseller", null]}, "installer_user_id": {"type": ["integer", "null"]}, "installer_name": {"type": "string"}, "installer_email": {"type": "string", "format": "email"}, "installer_ready": {"type": "boolean"}, "status": {"type": "string"}, "items": {"type": "array", "items": {"$ref": "#/components/schemas/FulfillmentGroupItem"}}}},
      "ConfigTemplateMetadata": {"type": "object", "description": "Safe metadata only; configuration bodies and credentials are never returned.", "properties": {"id": {"type": "integer"}, "name": {"type": "string"}, "description": {"type": "string"}, "status": {"type": "string"}, "channel_id": {"type": "integer"}, "channel_code": {"type": "string"}, "channel_name": {"type": "string"}}},
      "Batch": {"type": "object", "properties": {"id": {"type": "string", "format": "uuid"}, "batch_number": {"type": "string"}, "channel_id": {"type": "integer"}, "channel_name": {"type": "string"}, "customer_company_id": {"type": "string", "format": "uuid"}, "customer_name": {"type": "string"}, "status": {"type": "string"}, "scheduled_start": {"type": "string", "format": "date"}, "scheduled_end": {"type": "string", "format": "date"}, "notes": {"type": "string"}, "version": {"type": "integer", "description": "Send this value as expected_version when updating the Batch."}, "completed_at": {"type": ["string", "null"], "format": "date-time"}, "config_template_id": {"type": ["integer", "null"]}, "config_template": {"oneOf": [{"$ref": "#/components/schemas/ConfigTemplateMetadata"}, {"type": "null"}]}, "suggested_config_template_id": {"type": ["integer", "null"]}, "suggested_template_source_batch_id": {"type": "string", "format": "uuid"}, "suggested_template_source_batch_number": {"type": "string"}, "default_installer_payer": {"type": "string"}, "required_sku_quantity": {"type": "integer"}, "assigned_sku_quantity": {"type": "integer"}, "allocated_quantity": {"type": "integer"}, "planning_complete": {"type": "boolean"}, "release_ready": {"type": "boolean"}, "requires_config_template": {"type": "boolean"}, "created_at": {"type": "string", "format": "date-time"}, "updated_at": {"type": "string", "format": "date-time"}, "allocations": {"type": "array", "items": {"type": "object"}}, "fulfillment_groups": {"type": "array", "items": {"$ref": "#/components/schemas/FulfillmentGroup"}}}},
      "BatchInstaller": {"type": "object", "description": "Active reseller-scoped installer metadata; no OTP or identity secrets.", "properties": {"id": {"type": "integer"}, "name": {"type": "string", "format": "email"}, "display_name": {"type": "string"}, "channel_id": {"type": "integer"}}}
    }
  },
  "security": [{"BearerAuth": []}],
  "paths": {
    "/": {"get": {"summary": "Interactive API documentation", "security": [], "responses": {"200": {"description": "HTML documentation"}}}},
    "/openapi.json": {"get": {"summary": "OpenAPI document", "security": [], "responses": {"200": {"description": "OpenAPI JSON"}}}},
    "/healthz": {"get": {"summary": "Health check", "security": [], "responses": {"200": {"description": "Healthy"}}}},
    "/v1/auth/sessions": {"post": {"summary": "Exchange a verified Google or WorkOS credential for a database-backed Phone Home session", "security": [], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProviderSessionRequest"}}}}, "responses": {"201": {"description": "Session created"}, "401": {"description": "Identity is invalid or not provisioned"}}}},
    "/v1/auth/sessions/refresh": {"post": {"summary": "Rotate an expiring WorkOS provider session", "description": "Requires the opaque application bearer token, X-CSRF-Token, browser binding, and a rotating WorkOS refresh token.", "responses": {"200": {"description": "Provider session refreshed"}, "401": {"description": "Refresh authorization failed"}}}},
    "/v1/auth/session": {"delete": {"summary": "Revoke the current application session", "responses": {"200": {"description": "Session revoked"}}}},
    "/v1/me": {"get": {"summary": "Get the current scoped user and permissions", "responses": {"200": {"description": "Session profile", "content": {"application/json": {"schema": {"type": "object", "properties": {"user": {"$ref": "#/components/schemas/SessionProfile"}}}}}}}}},
    "/v1/channels": {"get": {"summary": "List visible reseller channels", "responses": {"200": {"description": "Channels"}}}, "post": {"summary": "Create a reseller and bind its WorkOS organization", "responses": {"201": {"description": "Channel created"}}}},
    "/v1/admin/channels/{channel_id}/profile": {"patch": {"summary": "Update a reseller's optional Cloud1 ID", "description": "Requires Colony-global users.manage permission. A null Cloud1 ID clears the existing linkage.", "parameters": [{"name": "channel_id", "in": "path", "required": true, "schema": {"type": "integer"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["cloud1_reseller_id"], "properties": {"cloud1_reseller_id": {"type": ["integer", "null"], "minimum": 1}}}}}}, "responses": {"200": {"description": "Channel updated"}, "403": {"description": "Colony-global administration required"}, "404": {"description": "Channel not found"}}}},
    "/v1/companies": {"get": {"summary": "List RLS-visible customer companies", "responses": {"200": {"description": "Companies"}}}, "post": {"summary": "Create a reseller-scoped customer", "responses": {"201": {"description": "Company created"}}}},
    "/v1/operations/companies/{company_id}": {"patch": {"summary": "Update an RLS-visible customer without changing reseller or Local ID", "description": "Cloud1 linkage and status changes require Colony-global orders.manage permission.", "parameters": [{"name": "company_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Company updated"}, "403": {"description": "Cloud1 or status change is not permitted"}, "404": {"description": "Company is not visible"}}}},
    "/v1/sites": {"get": {"summary": "List RLS-visible customer sites", "responses": {"200": {"description": "Sites"}}}, "post": {"summary": "Create a reseller-scoped customer site", "responses": {"201": {"description": "Site created"}}}},
    "/v1/operations/sites/{site_id}": {"patch": {"summary": "Update an RLS-visible site without changing reseller, customer, or Local ID", "description": "Cloud1 linkage and status changes require Colony-global orders.manage permission.", "parameters": [{"name": "site_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Site updated"}, "403": {"description": "Cloud1 or status change is not permitted"}, "404": {"description": "Site is not visible"}}}},
    "/v1/products": {"get": {"summary": "List active, orderable Products", "description": "Only Products with at least one associated SKU and no inactive SKU components are returned. Order lines reference Product IDs; SKU composition is snapshotted at Order creation.", "responses": {"200": {"description": "Products"}}}},
    "/v1/skus": {"get": {"summary": "List active warehouse and forecast SKUs", "responses": {"200": {"description": "SKUs"}}}},
    "/v1/admin/products": {"get": {"summary": "List Products and SKU associations for Colony catalog administration", "responses": {"200": {"description": "Products"}}}, "post": {"summary": "Create a Product independently with zero or more SKU associations", "responses": {"201": {"description": "Product created"}}}},
    "/v1/admin/products/{product_id}": {"patch": {"summary": "Update a Product and replace its many-to-many SKU composition", "parameters": [{"name": "product_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Product updated"}}}},
    "/v1/admin/skus": {"get": {"summary": "List all active and inactive SKUs for Colony catalog administration", "responses": {"200": {"description": "SKUs"}}}, "post": {"summary": "Create a warehouse SKU independently of Products", "responses": {"201": {"description": "SKU created"}}}},
    "/v1/admin/skus/{sku_id}": {"patch": {"summary": "Update SKU warehouse behavior, Cloud1 linkage, or active state", "parameters": [{"name": "sku_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "SKU updated"}}}},
    "/v1/orders": {"get": {"summary": "List RLS-visible Orders", "responses": {"200": {"description": "Orders"}}}, "post": {"summary": "Create a draft Order with Product-based lines", "description": "Each line references product_id or product_code. The API snapshots the Product's SKU components for later warehouse expansion.", "responses": {"201": {"description": "Order created"}}}},
    "/v1/operations/summary": {"get": {"summary": "Get authoritative RLS-visible Order and customer counts", "description": "Expected product-unit totals are returned only for Colony-global sessions.", "responses": {"200": {"description": "Operations dashboard summary"}}}},
    "/v1/orders/{order_id}": {"get": {"summary": "Get an RLS-visible Order", "parameters": [{"name": "order_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Order"}, "404": {"description": "Order not visible or missing"}}}},
    "/v1/orders/{order_id}/transitions": {"post": {"summary": "Apply an authorized Order state transition", "description": "Hold and cancellation require reasons. Acceptance and release require the customer and any referenced destination sites to be active and linked to Cloud1.", "parameters": [{"name": "order_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Order transitioned"}, "409": {"description": "Illegal transition or customer/site readiness requirement is not met"}}}},
    "/v1/operations/leads": {"get": {"summary": "List Colony-global expected-order leads", "parameters": [{"name": "status", "in": "query", "schema": {"type": "string", "enum": ["expected", "committed", "won", "lost", "cancelled"]}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "default": 50, "minimum": 1, "maximum": 200}}, {"name": "offset", "in": "query", "schema": {"type": "integer", "default": 0, "minimum": 0}}], "responses": {"200": {"description": "Leads"}, "403": {"description": "Colony-global access required"}}}, "post": {"summary": "Create a Colony-global reseller/customer lead with one or more SKU quantity lines", "responses": {"201": {"description": "Lead created"}, "403": {"description": "Colony-global access required"}}}},
    "/v1/operations/leads/{lead_id}": {"get": {"summary": "Get a Colony-global lead", "parameters": [{"name": "lead_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Lead"}, "403": {"description": "Colony-global access required"}}}, "patch": {"summary": "Update a Colony-global lead forecast status, date, confidence, or notes", "responses": {"200": {"description": "Lead updated"}, "403": {"description": "Colony-global access required"}}}},
    "/v1/users": {"get": {"summary": "List users visible to the signed user manager", "responses": {"200": {"description": "Users"}}}, "post": {"summary": "Create a multi-role scoped user", "description": "Partner users are created with a durable reseller-organization WorkOS invitation and never a Phone Home password.", "responses": {"201": {"description": "User created; WorkOS delivery state is included"}}}},
    "/v1/users/bulk": {"post": {"summary": "Create up to 100 users with one shared scope and role set", "description": "Partner-user creation is atomic locally. Individual organization-bound WorkOS invitations are delivered concurrently and failed deliveries remain retryable.", "responses": {"201": {"description": "Users created atomically; WorkOS delivery summary is included"}}}},
	    "/v1/admin/users/{user_id}/profile": {"patch": {"summary": "Update roles, installer phone, display name, or suspension state", "parameters": [{"name": "user_id", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "User updated"}}}},
	    "/v1/admin/autossh-servers": {"get": {"summary": "List AutoSSH servers", "responses": {"200": {"description": "AutoSSH servers"}}}, "post": {"summary": "Create an AutoSSH server and queue autossh_provision", "responses": {"202": {"description": "Server created and task accepted"}}}},
	    "/v1/admin/autossh-servers/{server_id}": {"get": {"summary": "Get an AutoSSH server", "parameters": [{"name": "server_id", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "AutoSSH server"}}}, "patch": {"summary": "Update an AutoSSH server and queue autossh_provision", "parameters": [{"name": "server_id", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"202": {"description": "Server updated and task accepted"}}}, "delete": {"summary": "Soft-delete an unassigned AutoSSH server and queue autossh_provision", "parameters": [{"name": "server_id", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"202": {"description": "Server deleted and task accepted"}, "409": {"description": "Devices remain assigned"}}}},
	    "/v1/admin/devices/{mac_addr}/autossh-server": {"post": {"summary": "Move a device to another AutoSSH server and queue autossh_config_update", "parameters": [{"name": "mac_addr", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"202": {"description": "Ports reassigned and task accepted"}}}},
	    "/v1/admin/devices/{mac_addr}/firmware-artifacts": {"get": {"summary": "List firmware files in GCS for a device", "parameters": [{"name": "mac_addr", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "Firmware objects"}}}},
	    "/v1/admin/devices/{mac_addr}/firmware-artifacts/download": {"get": {"summary": "Download one device firmware file through the API", "parameters": [{"name": "mac_addr", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "object", "in": "query", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "Firmware file"}, "404": {"description": "Object not found"}}}},
	    "/v1/warehouses": {"get": {"summary": "List warehouses and bins", "responses": {"200": {"description": "Warehouses"}}}, "post": {"summary": "Create a warehouse with default operational bins", "responses": {"201": {"description": "Warehouse created"}}}},
	    "/v1/admin/warehouses/{warehouse_id}": {"patch": {"summary": "Update warehouse identity, timezone, and address", "parameters": [{"name": "warehouse_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Warehouse updated"}, "403": {"description": "Warehouse administration requires the operations_admin or admin role"}}}, "delete": {"summary": "Delete an empty, otherwise-unreferenced warehouse and all of its bins", "parameters": [{"name": "warehouse_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"204": {"description": "Warehouse deleted"}, "403": {"description": "Warehouse administration requires the operations_admin or admin role"}, "409": {"description": "Inventory or operational history prevents deletion"}}}},
	    "/v1/admin/warehouses/{warehouse_id}/bins": {"post": {"summary": "Create a bin beneath a warehouse", "parameters": [{"name": "warehouse_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"201": {"description": "Warehouse bin created"}, "403": {"description": "Warehouse administration requires the operations_admin or admin role"}}}},
	    "/v1/admin/warehouse-bins/{bin_id}": {"patch": {"summary": "Update warehouse bin code, name, or operational type", "parameters": [{"name": "bin_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Warehouse bin updated"}, "403": {"description": "Warehouse administration requires the operations_admin or admin role"}}}, "delete": {"summary": "Delete an empty, otherwise-unreferenced warehouse bin", "parameters": [{"name": "bin_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"204": {"description": "Warehouse bin deleted"}, "403": {"description": "Warehouse administration requires the operations_admin or admin role"}, "409": {"description": "Inventory or operational history prevents deletion"}}}},
    "/v1/receipts": {"get": {"summary": "List inbound receipts", "responses": {"200": {"description": "Receipts"}}}, "post": {"summary": "Open an inbound receipt", "responses": {"201": {"description": "Receipt opened"}}}},
    "/v1/receipts/{receipt_id}/scans": {"post": {"summary": "Receive serialized or quantity inventory", "parameters": [{"name": "receipt_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"201": {"description": "Receipt scan accepted"}}}},
    "/v1/receipts/{receipt_id}/close": {"post": {"summary": "Close an inbound receipt", "parameters": [{"name": "receipt_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Receipt closed"}}}},
    "/v1/inventory": {"get": {"summary": "List bounded balances by reseller, SKU, warehouse, bin, and status", "parameters": [{"name": "warehouse_id", "in": "query", "schema": {"type": "string", "format": "uuid"}}, {"name": "status", "in": "query", "schema": {"type": "string"}}], "responses": {"200": {"description": "Inventory balances"}, "400": {"description": "Invalid filters or result exceeds the 5,000-row safety limit"}}}},
    "/v1/inventory/movements": {"post": {"summary": "Record an authorized inventory movement or adjustment", "responses": {"201": {"description": "Movement recorded"}}}},
    "/v1/inventory/devices/{mac}/readiness": {"post": {"summary": "Record prep and QA and make a serialized device available", "parameters": [{"name": "mac", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "Device available"}}}},
	    "/v1/batches": {"get": {"summary": "List active and recently closed fulfillment Batches", "description": "Returns every non-completed/non-cancelled Batch plus terminal Batches closed within the rolling previous 30 days.", "responses": {"200": {"description": "Batches"}}}, "post": {"summary": "Create a Batch from explicit Order-line Product quantities", "description": "A site plan may be supplied or added later while planned/held. Product allocations expand through immutable Order-line component SKUs.", "responses": {"201": {"description": "Batch created"}}}},
	    "/v1/batches/eligible-lines": {"get": {"summary": "List accepted or released Order lines and their remaining allocatable quantities", "description": "Use limit (maximum 500) and offset to continue through eligible lines. The response includes component SKU codes and quantity_per_product plus limit, offset, has_more, and next_offset. Results may also be narrowed with batch_id, channel_id, or customer_company_id.", "responses": {"200": {"description": "Eligible Order lines with component metadata and continuation"}}}},
    "/v1/config-templates": {"get": {"summary": "Search usable configuration-template metadata", "description": "Requires batches.manage. Returns only ID, name, description, status, channel metadata, and timestamps; never configuration bodies, passwords, SIM data, or credentials.", "responses": {"200": {"description": "Safe template metadata"}}}},
    "/v1/installers": {"get": {"summary": "List active installers visible to a Batch planner", "description": "The narrow directory is reseller-scoped by RLS and batches.manage.", "responses": {"200": {"description": "Installer metadata"}}}, "post": {"summary": "Create an installer-only user from Batch planning", "description": "Creates one reseller-scoped installer with SMS OTP identity. It never grants general user management, global scope, WorkOS credentials, or a Phone Home password.", "responses": {"201": {"description": "Installer created"}, "403": {"description": "Reseller is outside the signed planner scope"}}}},
    "/v1/batches/{batch_id}": {"get": {"summary": "Get a complete Batch destination plan", "description": "Includes Product allocations, physical component-SKU requirements, per-site assignments, installation settings, safe template metadata, and release readiness.", "parameters": [{"name": "batch_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Complete Batch plan"}, "404": {"description": "Batch not visible"}}}},
	    "/v1/operations/batches/{batch_id}": {"patch": {"summary": "Replace a planned Batch allocation and site plan", "description": "expected_version and the complete allocation set are required. When fulfillment_groups is present it replaces the site-first plan; omitting a site removes its assignments and returns those SKU quantities to unassigned demand. Planned/held only.", "parameters": [{"name": "batch_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Batch updated"}, "409": {"description": "Batch is stale, already released, or assignment/allocation quantities conflict"}}}},
    "/v1/batches/{batch_id}/release": {"post": {"summary": "Atomically release a complete site-first Batch plan", "description": "Fails without creating reservations or warehouse work unless every physical component SKU is assigned exactly once in aggregate, all service/shipping sites are active and Cloud1-linked, every assigned installer remains active and reseller-scoped, and a usable template is selected for K500A. Creates separate pick/pack/shipment work per site group.", "parameters": [{"name": "batch_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Batch released with one pick task per site"}, "409": {"description": "Destination, installer, inventory, or template plan is incomplete"}}}},
    "/v1/fulfillment/tasks": {"get": {"summary": "List pick, pack, and shipment work", "responses": {"200": {"description": "Fulfillment tasks"}}}},
    "/v1/pick-task-lines/{line_id}/scans": {"post": {"summary": "Record a serialized or quantity pick", "parameters": [{"name": "line_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"201": {"description": "Pick accepted"}}}},
    "/v1/pick-tasks/{pick_task_id}/pack": {"post": {"summary": "Validate contents and seal the package", "parameters": [{"name": "pick_task_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Shipment ready"}}}},
    "/v1/shipments": {"get": {"summary": "List shipments and serialized contents", "responses": {"200": {"description": "Shipments"}}}},
    "/v1/shipments/{shipment_id}/confirm": {"post": {"summary": "Confirm carrier and tracking and ship packed inventory", "parameters": [{"name": "shipment_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Shipment confirmed"}}}},
    "/v1/returns": {"get": {"summary": "List returns and dispositions", "responses": {"200": {"description": "Returns"}}}, "post": {"summary": "Receive a shipped serialized device into quarantine", "responses": {"201": {"description": "Return received"}}}},
    "/v1/return-items/{return_item_id}/disposition": {"post": {"summary": "Restock, repair, retain, return, or scrap a quarantined device", "parameters": [{"name": "return_item_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Disposition recorded"}}}},
    "/v1/admin/users/{user_id}/workos-invitation": {"post": {"summary": "Retry a queued or failed partner WorkOS invitation", "parameters": [{"name": "user_id", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Invitation delivered"}, "409": {"description": "No retryable invitation exists"}, "502": {"description": "Provider delivery failed and remains retryable"}}}},
    "/v1/admin/users/bulk-suspension": {"post": {"summary": "Suspend or reactivate up to 100 visible users atomically", "responses": {"200": {"description": "Users updated"}}}},
    "/v1/admin/users/bulk-delete": {"post": {"summary": "Soft-delete up to 100 visible users atomically", "description": "Blocks self-deletion, suspends each user, revokes active sessions, and retains the audited record.", "responses": {"200": {"description": "Users soft-deleted"}}}},
    "/v1/wifi/{mac_addr}": {"get": {"summary": "Get current Wi-Fi configuration", "description": "Returns the current private and guest pair settings, including configured passwords. App bearer authentication is required and responses are marked no-store.", "parameters": [{"name": "mac_addr", "in": "path", "required": true, "schema": {"type": "string"}}, {"$ref": "#/components/parameters/RequestID"}], "responses": {"200": {"description": "Current Wi-Fi configuration", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WiFiConfig"}}}}}}},
    "/v1/network-settings/devices/{mac_addr}": {"get": {"summary": "Get device network settings", "description": "Returns the enabled cellular and Ethernet priority order, preferred SIM slot, SIM auto-switch setting, and configured per-slot APNs. App bearer authentication is required and responses are marked no-store.", "parameters": [{"name": "mac_addr", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "Current network settings", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/NetworkSettings"}}}}}}, "patch": {"summary": "Update device network settings", "description": "Creates one config revision and queues a scoped apply_network_settings task containing only changed controls. Reordering interfaces does not replay SIM, APN, roaming, or unrelated device settings. Existing APNs cannot be cleared because the device agent cannot apply an empty APN.", "parameters": [{"name": "mac_addr", "in": "path", "required": true, "schema": {"type": "string"}}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/NetworkSettingsPatch"}}}}, "responses": {"200": {"description": "Already up to date"}, "202": {"description": "Config revision accepted"}, "409": {"description": "Maintenance is open, an auto-switch apply is pending, or the saved SIM preference changed"}, "422": {"description": "Invalid settings or unsupported auto-switch request"}}}},
    "/v1/{mac_addr}/ssid/{ssid_type}": {"patch": {"summary": "Update SSID configuration", "description": "Creates an unapplied config version and queues set_ssid_private for private/lan targets or set_ssid_guest for guest targets. Pair-level targets fan out to separate 2.4 GHz and 5 GHz device commands; band-specific targets update only that SSID. Guest updates may also carry captive_portal_enabled so Wi-Fi and portal commands are delivered in one task. Custom DNS fields are applied as manual DNS.", "parameters": [{"name": "mac_addr", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "ssid_type", "in": "path", "required": true, "schema": {"type": "string", "enum": ["lan", "private", "guest", "lan_2g", "lan_5g", "private_2g", "private_5g", "guest_2g", "guest_5g"]}}, {"$ref": "#/components/parameters/RequestID"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SSIDPatch"}}}}, "responses": {"200": {"description": "Accepted", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AcceptedTask"}}}}}}},
    "/v1/{mac_addr}/signal_tests": {"post": {"summary": "Run signal test", "parameters": [{"name": "mac_addr", "in": "path", "required": true, "schema": {"type": "string"}}, {"$ref": "#/components/parameters/RequestID"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SignalTestRequest"}}}}, "responses": {"202": {"description": "Accepted", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AcceptedTask"}}}}}}},
    "/v1/{mac_addr}/live_signal_tests": {"post": {"summary": "Start a live signal test", "description": "Starts one bounded device loop that emits radio context, ping latency, jitter, and packet loss every 10 seconds. It does not run TCP bandwidth tests.", "parameters": [{"name": "mac_addr", "in": "path", "required": true, "schema": {"type": "string"}}, {"$ref": "#/components/parameters/RequestID"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/LiveSignalTestRequest"}}}}, "responses": {"202": {"description": "Accepted", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AcceptedTask"}}}}, "409": {"description": "Selected interface is unavailable or the idempotency key conflicts"}}}},
    "/v1/live_signal_tests/{session_id}/stop": {"post": {"summary": "Stop a live signal test", "description": "Queues a stop command that names the exact original device task, preventing a delayed stop from cancelling a newer session.", "parameters": [{"name": "session_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"$ref": "#/components/parameters/RequestID"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/LiveSignalTestStopRequest"}}}}, "responses": {"202": {"description": "Accepted", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AcceptedTask"}}}}, "404": {"description": "Live signal test task not found"}}}},
    "/v1/signal_tests": {"get": {"summary": "List signal tests", "description": "Returns safe task metadata newest first. Fetch one task to read its progressive results.", "parameters": [{"name": "mac_addr", "in": "query", "required": true, "schema": {"type": "string"}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "default": 20, "maximum": 100}}, {"name": "offset", "in": "query", "schema": {"type": "integer", "default": 0, "minimum": 0}}, {"$ref": "#/components/parameters/RequestID"}], "responses": {"200": {"description": "Signal test history"}}}},
    "/v1/{mac_addr}/signal_test_comparisons": {"post": {"summary": "Compare cellular and WAN signal tests", "description": "Requires cellular1 and ethernet1 to be heartbeat-reported as available, then queues one device command that tests them sequentially and ranks their health.", "parameters": [{"name": "mac_addr", "in": "path", "required": true, "schema": {"type": "string"}}, {"$ref": "#/components/parameters/RequestID"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SignalTestComparisonRequest"}}}}, "responses": {"202": {"description": "Accepted", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AcceptedTask"}}}}, "409": {"description": "Cellular or WAN is unavailable"}}}},
    "/v1/signal_tests/{task_id}": {"get": {"summary": "Get signal test", "parameters": [{"name": "task_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"$ref": "#/components/parameters/RequestID"}], "responses": {"200": {"description": "Signal test status"}}}},
    "/v1/enhanced-sitehealth/{mac_addr}": {"get": {"summary": "Get enhanced SiteHealth", "description": "Returns the latest two-minute ping measurements for the heartbeat-reported primary interface and first standby. Measurements older than five minutes are returned as unknown.", "parameters": [{"name": "mac_addr", "in": "path", "required": true, "schema": {"type": "string"}}, {"$ref": "#/components/parameters/RequestID"}], "responses": {"200": {"description": "Latest interface health", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/EnhancedSiteHealth"}}}}}}},
    "/v1/{mac_addr}/restarts": {"post": {"summary": "Restart device", "parameters": [{"name": "mac_addr", "in": "path", "required": true, "schema": {"type": "string"}}, {"$ref": "#/components/parameters/RequestID"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RestartRequest"}}}}, "responses": {"200": {"description": "Accepted", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AcceptedTask"}}}}}}},
    "/v1/{mac_addr}/firmware_updates": {"post": {"summary": "Update firmware", "parameters": [{"name": "mac_addr", "in": "path", "required": true, "schema": {"type": "string"}}, {"$ref": "#/components/parameters/RequestID"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/FirmwareUpdateRequest"}}}}, "responses": {"200": {"description": "Accepted"}, "422": {"description": "Unsupported firmware version"}}}},
    "/v1/devops/devices": {"get": {"summary": "List devices", "parameters": [{"name": "search", "in": "query", "schema": {"type": "string"}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "default": 50, "maximum": 500}}, {"name": "offset", "in": "query", "schema": {"type": "integer", "default": 0, "minimum": 0}}], "responses": {"200": {"description": "Devices"}}}, "post": {"summary": "Create device", "description": "Devops-only endpoint that creates a device, allocates three autossh ports for SSH, HTTP, and LuCI, optionally inserts passwords, creates initial config version 1 from the default template, and generates Phone Home keys into security_keys. If the MAC already exists, the endpoint returns 409 unless confirm_regenerate_security_keys is true; confirmed existing-MAC requests regenerate only the Phone Home keys.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateDeviceRequest"}}}}, "responses": {"200": {"description": "Existing device security keys regenerated"}, "201": {"description": "Created", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateDeviceResponse"}}}}, "409": {"description": "Existing MAC requires explicit key regeneration confirmation"}}}},
    "/v1/devops/phone-home-versions": {"get": {"summary": "List Phone Home agent versions", "description": "Reads metadata for the Artifact Registry agent package and returns versions newest to oldest.", "responses": {"200": {"description": "Available versions", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PhoneHomeVersions"}}}}, "502": {"description": "Artifact Registry metadata unavailable"}}}},
    "/v1/devops/devices/{mac_addr}": {"get": {"summary": "Get device details and password history", "description": "Includes the latest active root password for authorized device readers. Only global admin sessions receive password history. Must not be cached.", "parameters": [{"name": "mac_addr", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "Device details", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeviceDetails"}}}}}}},
    "/v1/device-config-templates": {"get": {"summary": "List configuration templates", "description": "Requires a database session with devices.manage; templates are scoped to visible channels.", "responses": {"200": {"description": "Success"}, "403": {"description": "Insufficient permission"}, "422": {"description": "Invalid input"}}}, "post": {"summary": "Create a template from a device revision", "description": "Copies all normalized sections from the specified source configuration into a reusable template in the same channel.", "responses": {"201": {"description": "Success"}, "403": {"description": "Insufficient permission"}, "422": {"description": "Invalid input"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"source_config_id": {"type": "integer", "minimum": 1}, "name": {"type": "string", "maxLength": 40}, "description": {"type": "string", "maxLength": 4000}}, "required": ["source_config_id", "name"]}}}}}},
    "/v1/devices/{mac_addr}/config-versions": {"get": {"summary": "List device configuration versions", "description": "Returns version metadata newest first, scoped to the session.", "responses": {"200": {"description": "Success"}, "403": {"description": "Insufficient permission"}, "422": {"description": "Invalid input"}}, "parameters": [{"name": "mac_addr", "in": "path", "required": true, "schema": {"type": "string"}}]}},
    "/v1/devices/{mac_addr}/config-template": {"post": {"summary": "Assign and apply a configuration template", "description": "Enabling assignment immediately copies the template to a new device revision and queues apply_config. The template must belong to the same channel; an open maintenance window blocks application.", "responses": {"200": {"description": "Success"}, "403": {"description": "Insufficient permission"}, "422": {"description": "Invalid input"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"template_id": {"type": ["integer", "null"], "minimum": 1}, "enabled": {"type": "boolean"}}, "required": ["enabled"]}}}}, "parameters": [{"name": "mac_addr", "in": "path", "required": true, "schema": {"type": "string"}}]}},
    "/v1/admin/devices/{mac_addr}/firmware-builds": {"post": {"summary": "Build firmware for a configuration revision or template", "description": "Requires a global admin session and a saved root password. Provide config_id to build an existing device revision, template_id to first materialize a device config snapshot from a reusable template, or omit both to use the latest device revision. config_id and template_id are mutually exclusive.", "responses": {"202": {"description": "Success"}, "403": {"description": "Insufficient permission"}, "422": {"description": "Invalid input"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"config_id": {"type": "integer", "minimum": 1}, "template_id": {"type": "integer", "minimum": 1}, "remove_reset_file": {"type": "boolean", "default": false}, "options": {"type": "object", "additionalProperties": {"type": "string"}}}, "required": []}}}}, "parameters": [{"name": "mac_addr", "in": "path", "required": true, "schema": {"type": "string"}}]}},
    "/v1/me/settings": {"get": {"summary": "Read user preferences", "description": "Returns persisted account preferences.", "responses": {"200": {"description": "Success"}, "403": {"description": "Insufficient permission"}, "422": {"description": "Invalid input"}}}, "patch": {"summary": "Update user preferences", "description": "Theme and timezone affect presentation. auto uses the browser timezone with UTC fallback.", "responses": {"200": {"description": "Success"}, "403": {"description": "Insufficient permission"}, "422": {"description": "Invalid input"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"theme": {"type": "string", "enum": ["light", "dark"]}, "timezone": {"type": "string", "description": "auto or an IANA timezone name, such as America/Vancouver"}, "last_page": {"type": "string"}, "devices_page_size": {"type": "integer"}, "tasks_page_size": {"type": "integer"}}, "required": []}}}}}},
    "/v1/devops/devices/{mac_addr}/passwords/root": {"post": {"summary": "Create a randomized root password", "description": "Creates an active 16-character cryptographically random root password only when the device has no active root password.", "parameters": [{"name": "mac_addr", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"201": {"description": "Created", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateRootPasswordResponse"}}}}, "409": {"description": "An active root password already exists"}}}, "patch": {"summary": "Save a root password version", "description": "Requires devices.manage. Saves a new active version for future firmware builds; does not change a running device. Blank password generates 16 random characters.", "responses": {"201": {"description": "Success"}, "403": {"description": "Insufficient permission"}, "422": {"description": "Invalid input"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"password": {"type": "string", "maxLength": 80}}, "required": []}}}}, "parameters": [{"name": "mac_addr", "in": "path", "required": true, "schema": {"type": "string"}}]}},
    "/v1/devops/devices/{mac_addr}/versions": {"patch": {"summary": "Set device target versions", "parameters": [{"name": "mac_addr", "in": "path", "required": true, "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeviceVersionsPatch"}}}}, "responses": {"200": {"description": "Target version saved"}, "422": {"description": "Unsupported target version"}, "502": {"description": "Artifact Registry metadata unavailable"}}}},
    "/v1/devops/devices/{mac_addr}/cli_commands": {"post": {"summary": "Run CLI command", "parameters": [{"name": "mac_addr", "in": "path", "required": true, "schema": {"type": "string"}}, {"$ref": "#/components/parameters/RequestID"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CLICommandRequest"}}}}, "responses": {"202": {"description": "Accepted", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AcceptedTask"}}}}}}},
    "/v1/devops/tables": {"get": {"summary": "List managed tables", "responses": {"200": {"description": "Tables"}}}},
    "/v1/devops/tables/{table}": {"get": {"summary": "List table rows", "responses": {"200": {"description": "Rows"}}}, "post": {"summary": "Insert row", "responses": {"201": {"description": "Created"}}}},
    "/v1/devops/tables/{table}/{id}": {"get": {"summary": "Get row", "responses": {"200": {"description": "Row"}}}, "put": {"summary": "Replace row", "responses": {"200": {"description": "Row"}}}, "patch": {"summary": "Patch row", "responses": {"200": {"description": "Row"}}}, "delete": {"summary": "Delete row", "responses": {"204": {"description": "Deleted"}}}}
  }
}
