{"openapi":"3.0.3","info":{"title":"CUTEADMOA OLT Multi-Vendor REST API","description":"Unified REST API for Huawei, ZTE, BDCOM, VSOL, and Solitine OLT devices. Presents a single consistent JSON layer over vendor-specific CLI\/SNMP\/NETCONF protocols.","version":"1.0.0","termsOfService":"https:\/\/cuteadmoa.site","contact":{"name":"CUTEADMOA Platform","email":"support@cuteadmoa.site"},"license":{"name":"MIT License","url":"https:\/\/opensource.org\/licenses\/MIT"}},"servers":[{"url":"http:\/\/localhost:8000","description":"Development server"},{"url":"https:\/\/api.cuteadmoa.site","description":"Production server"}],"tags":[{"name":"health","description":"Overall OLT health endpoints"},{"name":"pons","description":"Per-PON statistics and status"},{"name":"onus","description":"ONU status and configuration management"}],"paths":{"\/":{"get":{"summary":"API root \u2014 quick info","description":"Return basic API metadata and available endpoints.","operationId":"root","tags":["health"],"responses":{"200":{"description":"API root response","content":{"application\/json":{"example":{"name":"CUTEADMOA OLT Multi-Vendor REST API","version":"1.0.0","docs":"\/api-docs","endpoints":{"olt_health":"\/olts\/{vendor}","pon_stats":"\/pons\/{vendor}","onu_status":"\/onus\/{vendor}","onu_update":"\/onus\/{vendor}\/{onu_id}"}},"schema":{"type":"object","properties":{"name":{"type":"string","description":"API name"},"version":{"type":"string","description":"API version"},"docs":{"type":"string","format":"uri","description":"Documentation URL"},"endpoints":{"type":"object","description":"Map of endpoint paths and descriptions"}},"required":["name","version","docs","endpoints"]}}}}}}},"\/olts\/{vendor}":{"get":{"summary":"Get overall health of an OLT vendor","description":"Returns the overall health status of an OLT device from the specified vendor. The response schema is vendor-agnostic \u2014 every driver maps its proprietary output to the canonical OLTHealth model regardless of the underlying protocol (CLI, SNMP, or NETCONF).","operationId":"getOltHealth","tags":["health"],"parameters":[{"name":"vendor","in":"path","required":true,"description":"Vendor name (lowercase, matches driver folder name)","schema":{"type":"string","enum":["huawei","zte","bdcom"]},"example":"huawei"}],"responses":{"200":{"description":"OLT health data","content":{"application\/json":{"example":{"status":"online","uptime":"2h 15m 30s","temperature":45.2,"cpu_usage":23.5,"memory_usage":67,"firmware_version":"V5.6.0","model":"MA5600T","voltage":3.3},"schema":{"$ref":"#\/components\/schemas\/OLTHealth"}}}},"400":{"description":"Invalid vendor name","content":{"application\/json":{"example":{"error":"Unsupported vendor: 'unknown'. Supported: huawei, zte, bdcom","detail":"See \/api-docs for valid values"},"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}}}}}},"503":{"description":"Device offline or timeout","content":{"application\/json":{"example":{"error":"Failed to parse health data from huawei vendor"},"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"\/pons\/{vendor}":{"get":{"summary":"Get per-PON statistics for a vendor","description":"Returns per-PON statistics and status for all PON ports on the specified OLT vendor. Each PON entry follows the same canonical PONStat schema regardless of vendor brand.","operationId":"getPons","tags":["pons"],"parameters":[{"name":"vendor","in":"path","required":true,"description":"Vendor name (lowercase, matches driver folder name)","schema":{"type":"string","enum":["huawei","zte","bdcom"]},"example":"huawei"}],"responses":{"200":{"description":"PON statistics list","content":{"application\/json":{"example":[{"pon_id":1,"status":"active","rx_power":-15.3,"tx_power":-5.2,"error_count":0,"onu_count":16,"distance":12.5},{"pon_id":2,"status":"idle","rx_power":-20.1,"tx_power":-8.4,"error_count":2,"onu_count":8,"distance":8.2}],"schema":{"type":"array","items":{"$ref":"#\/components\/schemas\/PONStat"}}}}},"400":{"description":"Invalid vendor name","content":{"application\/json":{"example":{"error":"Unsupported vendor: 'unknown'. Supported: huawei, zte, bdcom"},"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"\/onus\/{vendor}":{"get":{"summary":"Get ONU status and details for a vendor","description":"Returns ONU (Optical Network Unit) status details including serial number, operational status, description field, and VLAN tag. The description and VLAN fields are the primary writable fields \u2014 updated via PUT\/PATCH. Response schema is identical across all vendors.","operationId":"getOnus","tags":["onus"],"parameters":[{"name":"vendor","in":"path","required":true,"description":"Vendor name (lowercase, matches driver folder name)","schema":{"type":"string","enum":["huawei","zte","bdcom"]},"example":"huawei"}],"responses":{"200":{"description":"ONU status list","content":{"application\/json":{"example":[{"onu_id":1,"serial":"AEQ12345678","status":"online","description":"Living Room ONT","vlan":100,"rx_power":-20.5,"tx_power":-10.2},{"onu_id":2,"serial":"AEQ12345679","status":"degraded","description":null,"vlan":null,"rx_power":-25.1,"tx_power":-12.8}],"schema":{"type":"array","items":{"$ref":"#\/components\/schemas\/ONUStatus"}}}}},"400":{"description":"Invalid vendor name","content":{"application\/json":{"example":{"error":"Unsupported vendor: 'unknown'. Supported: huawei, zte, bdcom"},"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"\/onus\/{vendor}\/{onu_id}":{"patch":{"summary":"Update ONU description and\/or VLAN","description":"Push configuration changes to an ONU on the specified vendor's OLT. The most important fields to update are: description (human-readable ONU identifier) and VLAN tag (1-4094). Both fields are optional in the payload \u2014 send only the fields you want to change. All other ONU properties remain unchanged.","operationId":"updateOnuConfig","tags":["onus"],"parameters":[{"name":"vendor","in":"path","required":true,"description":"Vendor name (lowercase, matches driver folder name)","schema":{"type":"string","enum":["huawei","zte","bdcom"]},"example":"huawei"},{"name":"onu_id","in":"path","required":true,"description":"ONU identifier on the PON","schema":{"type":"integer","minimum":1,"maximum":256,"example":1}}],"requestBody":{"required":true,"content":{"application\/json":{"example":{"description":"Living Room ONT","vlan":100},"schema":{"$ref":"#\/components\/schemas\/ONUConfigUpdate"}}}},"responses":{"200":{"description":"Updated ONU status","content":{"application\/json":{"example":{"onu_id":1,"status":"online","description":"Living Room ONT","vlan":100},"schema":{"$ref":"#\/components\/schemas\/ONUStatus"}}}},"400":{"description":"Invalid payload or vendor","content":{"application\/json":{"example":{"error":"VLAN must be between 1 and 4094, got 50000","detail":"See \/api-docs for valid values"},"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}}}}}},"503":{"description":"Device timeout or command failed","content":{"application\/json":{"example":{"error":"Failed to push config to huawei onu 1"},"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}},"components":{"schemas":{"OLTHealth":{"type":"object","description":"Canonical overall health response \u2014 vendor-agnostic schema.","required":["status"],"properties":{"status":{"type":"string","description":"Overall operational status: online | degraded | offline","enum":["online","degraded","offline"],"example":"online"},"uptime":{"type":"string","description":"System uptime string (vendor-specific format normalized)","example":"2h 15m 30s"},"temperature":{"type":"number","description":"CPU temperature in Celsius","minimum":-50,"maximum":200,"exclusiveMinimum":false,"exclusiveMaximum":false,"example":45.2},"cpu_usage":{"type":"number","description":"CPU usage percentage","minimum":0,"maximum":100,"exclusiveMinimum":false,"exclusiveMaximum":false,"example":23.5},"memory_usage":{"type":"number","description":"Memory usage percentage","minimum":0,"maximum":100,"exclusiveMinimum":false,"exclusiveMaximum":false,"example":67},"firmware_version":{"type":"string","description":"Device firmware version","example":"V5.6.0"},"software_version":{"type":"string","description":"OS software version","example":"RSP 5.4(1)"},"model":{"type":"string","description":"OTL model identifier","example":"MA5600T"},"voltage":{"type":"number","description":"Power supply voltage in Volts","minimum":0,"maximum":500,"exclusiveMinimum":false,"exclusiveMaximum":false,"example":3.3},"last_seen":{"type":"string","description":"ISO-8601 timestamp of last successful poll","format":"date-time","example":"2026-09-03T04:55:00+06:00"},"raw":{"type":"object","description":"Vendor-specific raw data \u2014 excluded from standardized output","example":{"temperature":452,"cpu_usage":235,"status":"online"}}}},"PONStat":{"type":"object","description":"Canonical per-PON statistics schema.","required":["pon_id","status"],"properties":{"pon_id":{"type":"integer","description":"PON port identifier","minimum":1,"maximum":64,"example":1},"status":{"type":"string","description":"PON port status: active | idle | alarm | fault","enum":["active","idle","alarm","fault"],"example":"active"},"rx_power":{"type":"number","description":"Received optical power in dBm","minimum":-50,"maximum":0,"exclusiveMinimum":false,"exclusiveMaximum":false,"example":-15.3},"tx_power":{"type":"number","description":"Transmitted optical power in dBm","minimum":-50,"maximum":0,"exclusiveMinimum":false,"exclusiveMaximum":false,"example":-5.2},"error_count":{"type":"integer","description":"Error counter","minimum":0,"example":0},"onu_count":{"type":"integer","description":"Number of ONUs registered on this PON","minimum":0,"example":16},"distance":{"type":"number","description":"Distance in km to furthest ONU","minimum":0,"maximum":100,"exclusiveMinimum":false,"exclusiveMaximum":false,"example":12.5}}},"ONUStatus":{"type":"object","description":"Canonical ONU status \u2014 description and VLAN are writable via PUT\/PATCH.","required":["onu_id","status"],"properties":{"onu_id":{"type":"integer","description":"ONU identifier on the PON","minimum":1,"maximum":256,"example":1},"serial":{"type":"string","description":"ONU serial number","example":"AEQ12345678"},"status":{"type":"string","description":"ONU operational status: online | offline | degraded | unknown","enum":["online","offline","degraded","unknown"],"example":"online"},"description":{"type":"string","description":"ONU description field (writable via PUT\/PATCH)","maxLength":128,"example":"Living Room ONT"},"vlan":{"type":"integer","description":"VLAN tag assigned to this ONU","minimum":1,"maximum":4094,"example":100},"rx_power":{"type":"number","description":"Received power in dBm","minimum":-50,"maximum":0,"exclusiveMinimum":false,"exclusiveMaximum":false,"example":-20.5},"tx_power":{"type":"number","description":"Transmitted power in dBm","minimum":-50,"maximum":0,"exclusiveMinimum":false,"exclusiveMaximum":false,"example":-10.2}}},"ONUConfigUpdate":{"type":"object","description":"Payload for PUT\/PATCH \/onus\/{vendor}\/{onu_id} \u2014 update ONU description and\/or VLAN.","properties":{"description":{"type":"string","description":"New ONU description (max 128 chars)","maxLength":128,"example":"Living Room ONT"},"vlan":{"type":"integer","description":"New VLAN tag (1-4094)","minimum":1,"maximum":4094,"example":100}},"additionalProperties":false}}},"security":[],"externalDocs":{"description":"CUTEADMOA API Documentation","url":"https:\/\/cuteadmoa.site\/api-docs"}}