Requires ability: devices:read

Exact match on the device serial number. Returns a list with zero or one item, so the response envelope is the same as the other two searches.

This search never returns more than one device, so it does not accept page or per_page — meta is always { "page": 1, "per_page": 25, "total": 0 or 1 }.

curl -s "https://app.archacs.com.br/api/v1/search/serial?serial=ZTEGC8A1B2C3" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

{
  "data": [
    {
      "serial": "ZTEGC8A1B2C3",
      "name": "Casa do João",
      "status": "online",
      "last_inform": "2026-07-30T12:41:02-03:00",
      "first_seen": "2025-11-03T09:12:44-03:00",
      "manufacturer": "ZTE",
      "model": "F670L",
      "firmware": "V1.2.3P1",
      "data_model": "TR-098",
      "wan_ip": "100.64.7.9",
      "pppoe_username": "joe@isp",
      "tags": ["fibra"]
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 1 }
}

Requires ability: devices:read

Exact match on the PPPoE username (case-insensitive). A single login can legitimately have more than one CPE, so the result is paginated.

Accepts page (default 1) and per_page (default 25, capped at 100). A per_page above 100 is silently clamped down to 100, not rejected.

curl -s "https://app.archacs.com.br/api/v1/search/login?login=joe@isp&page=2&per_page=50" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

{
  "data": [
    {
      "serial": "ZTEGC8A1B2C3",
      "name": "Casa do João",
      "status": "online",
      "last_inform": "2026-07-30T12:41:02-03:00",
      "first_seen": "2025-11-03T09:12:44-03:00",
      "manufacturer": "ZTE",
      "model": "F670L",
      "firmware": "V1.2.3P1",
      "data_model": "TR-098",
      "wan_ip": "100.64.7.9",
      "pppoe_username": "joe@isp",
      "tags": []
    }
  ],
  "meta": { "page": 2, "per_page": 50, "total": 57 }
}

Requires ability: devices:read

Exact match on the WAN IP address. Under CGNAT the same IP can legitimately show up on more than one CPE, so the result is paginated too.

Accepts page (default 1) and per_page (default 25, capped at 100). A per_page above 100 is silently clamped down to 100, not rejected.

curl -s "https://app.archacs.com.br/api/v1/search/ip?ip=100.64.7.9&per_page=100" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

{
  "data": [
    {
      "serial": "ZTEGC8A1B2C3",
      "name": "Casa do João",
      "status": "online",
      "last_inform": "2026-07-30T12:41:02-03:00",
      "first_seen": "2025-11-03T09:12:44-03:00",
      "manufacturer": "ZTE",
      "model": "F670L",
      "firmware": "V1.2.3P1",
      "data_model": "TR-098",
      "wan_ip": "100.64.7.9",
      "pppoe_username": "joe@isp",
      "tags": []
    }
  ],
  "meta": { "page": 1, "per_page": 100, "total": 1 }
}

Requires ability: devices:read

Pre-mapped detail of a single device: identification, WAN, optical signal (when present), CPU and memory (when the model reports them), Wi-Fi radios and SSIDs, LAN, connected hosts and the latest completed diagnostics. Every block is best-effort — if the ACS backend fails to collect one of them, that block comes back empty and the rest of the response is still returned. resources is null on models that do not expose the TR-069 memory and CPU leaves, and each field inside it can be null on its own; memory is reported in KiB and both percentages are integers from 0 to 100. The values are a snapshot refreshed about once an hour, not a live reading. optical is null on devices with no optical interface (any non-PON CPE) and its fields carry the unit in the name — rx_power_dbm and tx_power_dbm in dBm, temperature_c in degrees Celsius, voltage_mv in millivolts. Only rx/tx and up are reported by every PON vendor we map today; temperature_c and voltage_mv come back null unless the vendor exposes them.

curl -s "https://app.archacs.com.br/api/v1/devices/ZTEGC8A1B2C3" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

{
  "data": {
    "device": {
      "serial": "ZTEGC8A1B2C3",
      "name": "Casa do João",
      "status": "online",
      "last_inform": "2026-07-30T12:41:02-03:00",
      "first_seen": "2025-11-03T09:12:44-03:00",
      "manufacturer": "ZTE",
      "model": "F670L",
      "firmware": "V1.2.3P1",
      "data_model": "TR-098",
      "wan_ip": "100.64.7.9",
      "pppoe_username": "joe@isp",
      "tags": ["fibra"],
      "hardware_version": "V1.0",
      "product_class": "F670L"
    },
    "wan": [
      {
        "name": "WAN1",
        "kind": "pppoe",
        "up": true,
        "ipv4": "100.64.7.9",
        "netmask": "255.255.255.255",
        "gateway": null,
        "dns": [],
        "ipv6": [],
        "pppoe_username": "joe@isp"
      }
    ],
    "optical": {
      "technology": "GPON",
      "vendor": "ZTE",
      "up": true,
      "rx_power_dbm": -22.52,
      "tx_power_dbm": 2.58,
      "temperature_c": null,
      "voltage_mv": null
    },
    "resources": {
      "cpu_percent": 3,
      "mem_total_kib": 119128,
      "mem_free_kib": 49884,
      "mem_used_percent": 58
    },
    "wifi": [
      {
        "band": "2.4GHz",
        "enabled": true,
        "channel": 6,
        "auto_channel": true,
        "ssids": [
          {
            "id": "a1b2c3d4e5f6",
            "name": "Casa-Joao",
            "enabled": true,
            "hidden": false,
            "security": "WPA2-PSK",
            "bssid": "AA:BB:CC:DD:EE:FF"
          }
        ]
      }
    ],
    "lan": {
      "ipv4": "192.168.1.1",
      "netmask": "255.255.255.0",
      "ports": [
        { "label": "LAN1", "connected": true, "speed_mbps": 1000 }
      ]
    },
    "hosts": [],
    "diagnostics": { "ping": null, "download": null, "upload": null },
    "collected_at": {
      "wan": "2026-07-30T12:00:00-03:00",
      "wifi": "2026-07-30T12:00:00-03:00",
      "optical": "2026-07-30T12:00:00-03:00",
      "hosts": null
    }
  }
}

Forcing a fresh collection: ?refresh=1

The rest of data is exactly the same shape as above — still the cached copy. refresh is the only new field, and it never carries fresh values itself: poll again shortly and compare collected_at to know when the new data has landed.

curl -s "https://app.archacs.com.br/api/v1/devices/ZTEGC8A1B2C3?refresh=1" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

{
  "data": {
    "...": "same device/wan/optical/resources/wifi/lan/hosts/diagnostics/collected_at as above...",
    "refresh": {
      "requested": true,
      "connection_request": "ok",
      "hint": "poll again in ~30s and compare collected_at"
    }
  }
}

Second ?refresh=1 within 2 minutes of the previous one: throttled, still 200

The read itself never fails because of this throttle — only the new collection is declined. retry_after_seconds tells the integrator how long to wait before asking again. refresh.reason has three possible values: throttled (shown here), nothing_to_refresh (the device has no WAN, Wi-Fi or optical object to collect yet — typically a CPE that has only just checked in) and upstream_error (the ACS backend refused the queueing; the read still succeeded). Only throttled carries retry_after_seconds.

curl -s "https://app.archacs.com.br/api/v1/devices/ZTEGC8A1B2C3?refresh=1" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

{
  "data": {
    "...": "same device/wan/optical/resources/wifi/lan/hosts/diagnostics/collected_at as above...",
    "refresh": {
      "requested": false,
      "reason": "throttled",
      "retry_after_seconds": 87
    }
  }
}

Requires ability: devices:write

Queues a reboot. Always responds 202: the CPE restarts when it receives the command, not at the time of this call. A second reboot on the same device within 5 minutes is rejected with reboot_throttled, because it drops the subscriber's connection and the integrator needs to know it did not happen — unlike ?refresh=1, this never degrades silently.

curl -s -X POST "https://app.archacs.com.br/api/v1/devices/ZTEGC8A1B2C3/reboot" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

HTTP/1.1 202 Accepted
{
  "data": {
    "accepted": ["reboot"],
    "rejected": [],
    "queued": 1,
    "connection_request": "ok",
    "hint": "the device reboots when it receives the command; confirm via GET /api/v1/devices/ZTEGC8A1B2C3"
  }
}

Requires ability: devices:write

Changes the SSID and/or password of one Wi-Fi network. Target the network either by band (2.4GHz, 5GHz, 6GHz or all) or by the id returned in the device detail's wifi.*.ssids[].id — never by TR-069 path. Leaving password out keeps the current one. All target networks are written in a single batch, so one CWMP session applies every change instead of one session per network.

Which networks get written: with ssid_id, exactly that one. Without it, the primary network of each radio the band selects (band steering keeps 2.4 GHz and 5 GHz identical, so both are written). "Primary" means the single network on the air on that radio. If a radio has more than one network on the air — a guest network switched on is the usual case — the request is refused with 409 ambiguous_ssid and nothing is written: neither data model exposes a reliable "this is the guest network" flag, so the API will not guess which one the subscriber meant. Pick the network explicitly with ssid_id (from the device detail) and repeat the call.

curl -s -X PUT "https://app.archacs.com.br/api/v1/devices/ZTEGC8A1B2C3/wifi" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"band":"all","password":"novaSenha123"}'

HTTP/1.1 202 Accepted
{
  "data": {
    "accepted": ["password"],
    "rejected": [],
    "networks": [
      { "ssid_id": "a1b2c3d4e5f6", "band": "2.4GHz", "name": "Casa-Joao",
        "accepted": ["password"], "rejected": [] },
      { "ssid_id": "f6e5d4c3b2a1", "band": "5GHz", "name": "Casa-Joao",
        "accepted": ["password"], "rejected": [] }
    ],
    "queued": 2,
    "connection_request": "ok",
    "hint": "confirm via GET /api/v1/devices/ZTEGC8A1B2C3 — compare collected_at.wifi"
  }
}

Nothing to change: the SSID sent is the one already configured

Still 202, with accepted: [] and queued: 0 — a change that would be a no-op is not queued, because an empty CWMP session wakes the CPE up for nothing. connection_request comes back "skipped" for the same reason: no session was needed. Check queued to know whether anything was actually sent to the device.

curl -s -X PUT "https://app.archacs.com.br/api/v1/devices/ZTEGC8A1B2C3/wifi" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"band":"all","ssid":"Casa-Joao"}'

HTTP/1.1 202 Accepted
{
  "data": {
    "accepted": [],
    "rejected": [],
    "networks": [
      { "ssid_id": "a1b2c3d4e5f6", "band": "2.4GHz", "name": "Casa-Joao",
        "accepted": [], "rejected": [] }
    ],
    "queued": 0,
    "connection_request": "skipped",
    "hint": "confirm via GET /api/v1/devices/ZTEGC8A1B2C3 — compare collected_at.wifi"
  }
}

One network accepts the change and another refuses it

The top-level accepted and rejected are the union across every network written, so the same item can appear in both when one radio accepts it and another does not (some vendors lock the SSID on one radio only). networks is what disambiguates: it reports, per network, exactly what was accepted and what was refused.

curl -s -X PUT "https://app.archacs.com.br/api/v1/devices/ZTEGC8A1B2C3/wifi" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"band":"all","ssid":"Casa-Nova"}'

HTTP/1.1 202 Accepted
{
  "data": {
    "accepted": ["ssid"],
    "rejected": ["ssid"],
    "networks": [
      { "ssid_id": "a1b2c3d4e5f6", "band": "2.4GHz", "name": "Casa-Joao",
        "accepted": ["ssid"], "rejected": [] },
      { "ssid_id": "f6e5d4c3b2a1", "band": "5GHz", "name": "Casa-Joao",
        "accepted": [], "rejected": ["ssid"] }
    ],
    "queued": 1,
    "connection_request": "ok",
    "hint": "confirm via GET /api/v1/devices/ZTEGC8A1B2C3 — compare collected_at.wifi"
  }
}

Requires ability: devices:write

Issues a short-lived signed URL to that device's page, for a human — not another system — to open in a browser. Whoever opens it gets full operator power over that one device (reboot, Wi-Fi, PPPoE, settings) with no account on this platform, so this requires devices:write: issuing the link cannot be cheaper than acting through the API itself, or a read-only token would grant write access through the browser.

Valid for 15 minutes by default (configurable by the operator running this platform) and reusable within that window — opening the same URL more than once still works, no need to request a fresh link per click. The link only opens that device's page; unlike the other endpoints on this page, it is not a data endpoint and its response is not wrapped in data.

curl -s -X POST "https://app.archacs.com.br/api/v1/devices/ZTEGC8A1B2C3/share-link" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

{
  "url": "https://app.archacs.com.br/d/acme/ZTEGC8A1B2C3?expires=1782900000&signature=9f2b7c…",
  "expires_at": "2026-07-30T12:56:02-03:00"
}