{"openapi":"3.1.0","info":{"title":"OLT Multi-Vendor REST API","description":"Unified REST API for OLT devices — **API only, no frontend**.\n\nInitial support: **BDCOM, VSOL, Solitine** (EPON + GPON). Extended: **Huawei MA series, ZTE C3xx** (GPON).\n\nThree core operations:\n1. Read overall OLT health — `GET /olts/{vendor}`\n2. Per-PON statistics and status — `GET /pons/{vendor}`\n3. ONU status + push config (description / VLAN) — `GET /onus/{vendor}`, `PUT|PATCH /onus/{vendor}/{onu_id}`\n\nVendors are configured with credentials via environment variables (see `.env.example`). Without credentials the API runs in simulation mode; with credentials and `LIVE_MODE=true` it executes the equivalent CLI on the device.","version":"2.1.0"},"paths":{"/health":{"get":{"tags":["health"],"summary":"Service health","operationId":"service_health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/olts/{vendor}":{"get":{"tags":["health"],"summary":"Overall health of an OLT","operationId":"get_olt_health_olts__vendor__get","parameters":[{"name":"vendor","in":"path","required":true,"schema":{"type":"string","description":"Vendor: bdcom | vsol | solitine | huawei | zte","title":"Vendor"},"description":"Vendor: bdcom | vsol | solitine | huawei | zte"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OLTHealth"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/pons/{vendor}":{"get":{"tags":["pons"],"summary":"Per-PON statistics (EPON + GPON)","operationId":"get_pons_pons__vendor__get","parameters":[{"name":"vendor","in":"path","required":true,"schema":{"type":"string","description":"Vendor name","title":"Vendor"},"description":"Vendor name"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PONStat"},"title":"Response Get Pons Pons  Vendor  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/onus/{vendor}":{"get":{"tags":["onus"],"summary":"ONU status details","operationId":"get_onus_onus__vendor__get","parameters":[{"name":"vendor","in":"path","required":true,"schema":{"type":"string","description":"Vendor name","title":"Vendor"},"description":"Vendor name"},{"name":"pon_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pon Id"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ONUStatus"},"title":"Response Get Onus Onus  Vendor  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/onus/{vendor}/{onu_id}":{"get":{"tags":["onus"],"summary":"Single ONU detail","operationId":"get_onu_detail_onus__vendor___onu_id__get","parameters":[{"name":"vendor","in":"path","required":true,"schema":{"type":"string","title":"Vendor"}},{"name":"onu_id","in":"path","required":true,"schema":{"type":"integer","maximum":256,"minimum":1,"title":"Onu Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ONUStatus"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]},"put":{"tags":["onus"],"summary":"Update ONU description and/or VLAN (PUT)","operationId":"put_onu_config_onus__vendor___onu_id__put","parameters":[{"name":"vendor","in":"path","required":true,"schema":{"type":"string","description":"Vendor name","title":"Vendor"},"description":"Vendor name"},{"name":"onu_id","in":"path","required":true,"schema":{"type":"integer","maximum":256,"minimum":1,"title":"Onu Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ONUConfigUpdate","description":"e.g. {\"description\": \"Living Room ONT\", \"vlan\": 100}"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ONUUpdateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]},"patch":{"tags":["onus"],"summary":"Update ONU description and/or VLAN (PATCH — partial)","operationId":"patch_onu_config_onus__vendor___onu_id__patch","parameters":[{"name":"vendor","in":"path","required":true,"schema":{"type":"string","description":"Vendor name","title":"Vendor"},"description":"Vendor name"},{"name":"onu_id","in":"path","required":true,"schema":{"type":"integer","maximum":256,"minimum":1,"title":"Onu Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ONUConfigUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ONUUpdateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/api/v1/devices":{"get":{"tags":["devices","credentials"],"summary":"Per-vendor credential configuration status","operationId":"list_devices_api_v1_devices_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"ApiKeyAuth":[]}]}},"/api/v1/devices/{vendor}/test":{"post":{"tags":["devices","credentials"],"summary":"Test device reachability (TCP connect)","operationId":"test_device_api_v1_devices__vendor__test_post","parameters":[{"name":"vendor","in":"path","required":true,"schema":{"type":"string","title":"Vendor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/api/v1/devices/{vendor}/credentials":{"post":{"tags":["credentials"],"summary":"⚠ MANDATORY — add or update device credentials for a vendor","description":"**This is the mandatory first step before any live device access.**\n\nRegister the OLT management credentials the client provides. Until a vendor has credentials registered here (or via environment variables), every endpoint for that vendor runs in **simulation mode** and no real OLT is touched.\n\n- Passwords are stored server-side with 0600 permissions and are **never** returned by GET endpoints.\n- `live_mode: true` switches this vendor to real device execution.\n- Re-POST the same vendor to update any field (partial values override).","operationId":"add_device_credentials_api_v1_devices__vendor__credentials_post","parameters":[{"name":"vendor","in":"path","required":true,"schema":{"type":"string","title":"Vendor"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceCredentials"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Add Device Credentials Api V1 Devices  Vendor  Credentials Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]},"delete":{"tags":["credentials"],"summary":"Remove stored credentials for a vendor (back to simulation)","operationId":"delete_device_credentials_api_v1_devices__vendor__credentials_delete","parameters":[{"name":"vendor","in":"path","required":true,"schema":{"type":"string","title":"Vendor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/api/v1/devices/live-mode":{"patch":{"tags":["credentials"],"summary":"Toggle live execution globally (on/off)","operationId":"toggle_live_mode_api_v1_devices_live_mode_patch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveModeToggle"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}}},"components":{"schemas":{"DeviceCredentials":{"properties":{"host":{"type":"string","minLength":3,"title":"Host","description":"OLT management IP or hostname, e.g. 10.0.0.11"},"port":{"anyOf":[{"type":"integer","maximum":65535.0,"minimum":1.0},{"type":"null"}],"title":"Port","description":"Leave empty for the vendor default (22 SSH / 23 Telnet)"},"protocol":{"anyOf":[{"type":"string","enum":["ssh","telnet"]},{"type":"null"}],"title":"Protocol","description":"Leave empty for the vendor default"},"username":{"type":"string","minLength":1,"title":"Username","description":"CLI username"},"password":{"type":"string","minLength":1,"title":"Password","description":"CLI password"},"snmp_community":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Snmp Community","description":"SNMP v2c community (default: public)"},"pon_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Pon Types","description":"EPON and/or GPON, e.g. \"EPON,GPON\" — defaults to the vendor full set"},"live_mode":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Live Mode","description":"true = execute generated CLI on the device; false = simulation only"}},"type":"object","required":["host","username","password"],"title":"DeviceCredentials","description":"Payload for POST /api/v1/devices/{vendor}/credentials — MANDATORY for live access."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LiveModeToggle":{"properties":{"live_mode":{"type":"boolean","title":"Live Mode","description":"true = execute generated CLI on real devices"}},"type":"object","required":["live_mode"],"title":"LiveModeToggle"},"OLTHealth":{"properties":{"vendor":{"type":"string","title":"Vendor"},"status":{"type":"string","enum":["online","degraded","offline"],"title":"Status"},"mode":{"type":"string","enum":["live","simulation"],"title":"Mode"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"OLT model identifier"},"uptime":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uptime","description":"System uptime"},"temperature":{"anyOf":[{"type":"number","maximum":200.0,"minimum":-50.0},{"type":"null"}],"title":"Temperature","description":"CPU temperature C"},"cpu_usage":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Cpu Usage","description":"CPU usage %"},"memory_usage":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Memory Usage","description":"Memory usage %"},"firmware_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Firmware Version"},"protocols":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Protocols"},"pon_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Pon Types","description":"EPON and/or GPON"},"last_seen":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Seen","description":"ISO-8601 last successful poll"}},"type":"object","required":["vendor","status","mode"],"title":"OLTHealth","description":"Canonical health response — every vendor maps to this shape."},"ONUConfigUpdate":{"properties":{"description":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Description"},"vlan":{"anyOf":[{"type":"integer","maximum":4094.0,"minimum":1.0},{"type":"null"}],"title":"Vlan"}},"type":"object","title":"ONUConfigUpdate","description":"Payload for PUT/PATCH /onus/{vendor}/{onu_id} — send only fields to change."},"ONUStatus":{"properties":{"vendor":{"type":"string","title":"Vendor"},"onu_id":{"type":"integer","maximum":256.0,"minimum":1.0,"title":"Onu Id"},"pon_id":{"anyOf":[{"type":"integer","maximum":128.0,"minimum":1.0},{"type":"null"}],"title":"Pon Id"},"serial":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Serial"},"status":{"type":"string","enum":["online","offline","degraded","unknown"],"title":"Status"},"description":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Description","description":"Writable via PUT/PATCH"},"vlan":{"anyOf":[{"type":"integer","maximum":4094.0,"minimum":1.0},{"type":"null"}],"title":"Vlan","description":"Writable via PUT/PATCH"},"rx_power":{"anyOf":[{"type":"number","maximum":10.0,"minimum":-50.0},{"type":"null"}],"title":"Rx Power"},"tx_power":{"anyOf":[{"type":"number","maximum":10.0,"minimum":-50.0},{"type":"null"}],"title":"Tx Power"},"uptime":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uptime"}},"type":"object","required":["vendor","onu_id","status"],"title":"ONUStatus","description":"Canonical ONU status — description and VLAN are the writable fields."},"ONUUpdateResponse":{"properties":{"onu":{"$ref":"#/components/schemas/ONUStatus"},"updated":{"additionalProperties":{"type":"boolean"},"type":"object","title":"Updated"},"push":{"$ref":"#/components/schemas/PushResult"}},"type":"object","required":["onu","updated","push"],"title":"ONUUpdateResponse"},"PONStat":{"properties":{"vendor":{"type":"string","title":"Vendor"},"pon_id":{"type":"integer","maximum":128.0,"minimum":1.0,"title":"Pon Id","description":"PON port identifier"},"pon_type":{"type":"string","enum":["EPON","GPON"],"title":"Pon Type","description":"EPON or GPON"},"status":{"type":"string","enum":["active","idle","alarm","fault"],"title":"Status"},"onu_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Onu Count"},"rx_power":{"anyOf":[{"type":"number","maximum":10.0,"minimum":-50.0},{"type":"null"}],"title":"Rx Power","description":"dBm"},"tx_power":{"anyOf":[{"type":"number","maximum":10.0,"minimum":-50.0},{"type":"null"}],"title":"Tx Power","description":"dBm"},"error_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Error Count"},"distance_km":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Distance Km"}},"type":"object","required":["vendor","pon_id","pon_type","status"],"title":"PONStat","description":"Canonical per-PON statistics."},"PushResult":{"properties":{"mode":{"type":"string","enum":["live","simulation"],"title":"Mode"},"commands":{"items":{"type":"string"},"type":"array","title":"Commands","description":"CLI commands generated/executed"},"persist":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Persist"},"executed":{"type":"boolean","title":"Executed","default":false},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail"}},"type":"object","required":["mode"],"title":"PushResult"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Token","description":"Paste your API token. Get the test token from the landing page banner."}}}}