API User Guide
Introduction
Mosaic One provides the ability to troubleshoot problems in the network across multiple software systems in the residential broadband network. Mosaic One correlates data from these disparate systems and provides root cause analysis with expert insights to quickly resolve issues. The Mosaic One API extends the capabilities of Mosaic One providing access to the power of Mosaic One for integration with customer management and billing systems, partner integrators, and other API use cases. For additional information on Mosaic One API or to obtain access to the tool, contract your Adtran sales representative.
This guide covers how to use the Mosaic One API and walks through some of the most common operations. Use the examples to quickly get started integrating the API into your own solutions. This guide will use cURL in the various examples, though the same concepts will apply regardless of the client used for the REST operations.
Authentication
Every request made to the Mosaic One API will require two header fields to be present. These fields should be provided to you during the onboarding process.
X-Api-Key
The secret API generated specifically for authenticated access to the API. This key may change for multiple reasons, including key rotation, security compromise, or user request. This key is provided specifically and only for the user, and should be guarded as a security secret value.
For the remainder of this user guide, we will use a fictional API key of:
ads2s_12ad34tr56an78_zy09xw87vu65ts43rq21po01
X-Tenant
The tenant ID associated with the user company. The tenant name should be provided during onboarding, and will never change.
For the remainder of this user guide, we will use the fictional tenant id of:
adtran.
Guides
Retrieving a Subscriber
You can retrieve the information for a single subscriber by referencing the subscriber's account number and the associated API endpoint. For a subscriber with an account number of 54322, this would look like:
curl --location 'https://us.m1api.adtran.cloud/subscribers/account-number=54322' \
--header 'X-Api-Key: ads2s_12ad34tr56an78_zy09xw87vu65ts43rq21po01' \
--header 'X-Tenant: adtran'
If the account exists, the GET response will contain the subscriber information:
{
"subscriber-id": "0a1982a5-7489-43f1-b350-e04e40d4dcc5",
"name": "Subscriber, Example",
"account-number": "54322",
"address": "123 Example Way",
"city": "Madison",
"state": "AL",
"zip-code": "35758",
"phone-number": "1012227788",
"care-url": "https://m1.adtran.cloud/dashboard/adtran/care/subscriber/m1/0a1982a5-7489-43f1-b350-e04e40d4dcc5",
"subscriber-type": "RESIDENTIAL",
"service-count": 1,
"services": [
{
"service-id": "ab3b9569-defb-4b05-8ad7-b41dcfedf3ca",
"service-url": "https://us.m1api.adtran.cloud/subscribers/account-number=54322/status/service=ab3b9569-defb-4b05-8ad7-b41dcfedf3ca",
"service-type": "BROADBAND",
"package-name": "INT16R 19.2M/1.2M",
"provisioned-downstream-rate": 19200000,
"provisioned-upstream-rate": 1200000,
"max-attainable-downstream-rate": null,
"max-attainable-upstream-rate": null,
"service-address-street-address": "123 Example Way",
"service-address-city": "Madison",
"service-address-state": "AL",
"service-address-zip": "35758"
}
]
}
Retrieving a Service
Using the service-url from the example response above, you can retrieve the information for a single service by calling that endpoint with the same headers. Continuing the above example, this would look like:
curl --location 'https://us.m1api.adtran.cloud/subscribers/account-number=54322/status/service=ab3b9569-defb-4b05-8ad7-b41dcfedf3ca' \
--header 'X-Api-Key: ads2s_12ad34tr56an78_zy09xw87vu65ts43rq21po01' \
--header 'X-Tenant: adtran'
If the service exists, the GET response will contain the service information. Note that all fields are optional as not all services have all fields.
{
"home-network": {
"gateway": {
"equipment-type": "RESIDENTIAL_GATEWAY",
"name": "ROOM 1",
"ssid": "Example Subscriber's Wifi",
"part-number": "PP403Z",
"serial-number": "EB85B00CDD",
"wan-ip": null,
"wan-mac": "e4:c0:e2:21:db:68",
"ip-addresses": [
"192.168.1.174",
"207.229.97.200",
"fe80::e6c0:e2ff:fe21:db68/64",
"fd41:2754:bfd6::549/128",
"fd41:2754:bfd6:0:e6c0:e2ff:fe21:db68/64"
],
"public-ip": "207.229.97.200",
"vendor": "Plume",
"software-version": "6.4.1-35-gf5f999-prod",
"hardware-version": "6.4.1-35-gf5f999-prod",
"booted-at": "2024-12-12T18:54:47.000Z",
"uptime": 441415,
"oper-state": "UNKNOWN"
},
"devices": [
{
"hostname": "Amazon Echo",
"ip-addresses": [
"192.168.1.179"
],
"mac-address": "20:a1:71:0b:eb:25",
"oper-state": "UP",
"connection-type": "WIFI",
"upstream-rssi": -59,
"brand": "Amazon",
"connected-to": "EB85B00CDD",
"connection-state-change-at": "2024-12-15T21:25:36.636Z",
"device-source": "PLUME",
"wifi-generation": "UNAVAILABLE",
"wifi-standard": "UNAVAILABLE",
"device-link": "https://adtran.gamma.central.plume.com/customer/652555d7fcc9fe000bdae81e/location/652555d7fcc9fe000bdae81f/devices/20:a1:71:0b:eb:25"
},
{
"hostname": "Adtran 4b:41:11",
"ip-addresses": [],
"mac-address": "cc:66:18:4b:41:11",
"oper-state": "DOWN",
"connection-type": "WIRED",
"upstream-rssi": null,
"brand": null,
"connected-to": null,
"connection-state-change-at": "2024-12-06T03:13:46.000Z",
"device-source": "PLUME",
"wifi-generation": "UNAVAILABLE",
"wifi-standard": "UNAVAILABLE",
"device-link": "https://adtran.gamma.central.plume.com/customer/652555d7fcc9fe000bdae81e/location/652555d7fcc9fe000bdae81f/devices/cc:66:18:4b:41:11"
}
],
"mesh-nodes": [
{
"serial-number": "LC8AE0002F",
"name": "ROOM 2",
"backhaul-type": "WIFI",
"device-model": "PP603X",
"ip-addresses": [
"192.168.1.168",
"207.229.97.200",
"fd41:2754:bfd6:0:7c9f:7ff:fedd:3899/64",
"fd41:2754:bfd6::80f/128",
"fe80::7c9f:7ff:fedd:3899/64"
],
"mac-address": "7c:9f:07:dd:38:99",
"connection-state": "CONNECTED",
"connected-device-count": 0,
"connection-state-change-at": "2024-12-12T18:56:33.884Z",
"rssi": -52,
"device-link": "https://adtran.gamma.central.plume.com/customer/652555d7fcc9fe000bdae81e/location/652555d7fcc9fe000bdae81f/nodes/LC8AE0002F"
}
]
},
"access-network": {
"onu": {
"light-levels": {
"rx": -20.1,
"rx-retrieved-on": "2024-12-17 21:31:42",
"rx-state": "GOOD",
"tx": 3.9,
"tx-retrieved-on": "2024-12-17 21:31:42",
"tx-state": "GOOD"
},
"serial-number": "ADTN17271254"
},
"olt": {
"light-levels": {
"rx": -20.0,
"rx-retrieved-on": "2024-12-17 21:31:42",
"rx-state": "GOOD",
"tx": 3.8,
"tx-retrieved-on": "2024-12-17 21:31:42",
"tx-state": "GOOD"
}
},
"admin-state": "ENABLED",
"admin-state-retrieved-on": "2024-12-17 21:31:42",
"oper-state": "UP",
"oper-state-retrieved-on": "2024-12-17 21:31:42"
},
"service-actions": {
"reboot-rg": "https://us.m1api.adtran.cloud/subscribers/account-number=54322/service=ab3b9569-defb-4b05-8ad7-b41dcfedf3ca/reboot-rg",
"reboot-circuit": "https://us.m1api.adtran.cloud/subscribers/account-number=54322/service=ab3b9569-defb-4b05-8ad7-b41dcfedf3ca/reboot-circuit"
}
}
Executing Actions
Using the service-actions from the example response above, you can execute actions on a service to aid in troubleshooting. Continuing the above example, executing the /reboot-rg endpoint would look like:
curl --location 'https://us.m1api.adtran.cloud/subscribers/account-number=54322/service=ab3b9569-defb-4b05-8ad7-b41dcfedf3ca/reboot-rg' \
-X POST \
--header 'X-Api-Key: ads2s_12ad34tr56an78_zy09xw87vu65ts43rq21po01' \
--header 'X-Tenant: adtran'
Service Action Notes:
- Successfully executing sevice-actions requires elevated permissions on the API key.
- Action requests are POSTs and not GETs.