# modem software upgrades — NCM API

Group-level modem firmware upgrades. List the available modem software versions, each tagged with its carrier, package version, modem type and minimum router version, then create an upgrade to roll one out and poll or update it by ID. Upgrades target groups, not individual routers.

Base URL: https://api.cradlepointecm.com

### GET /api/v3/modem_software_versions

List available modem packages

Returns a list of modem packages available for a group

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| filter[group] | query | integer | yes | Group ID to get modem firmware images information |
| page[size] | query | integer | no | Number of results to return per page (max 50, default 20) |
| page[after] | query | string | no | Cursor for next page |
| page[before] | query | string | no | Cursor for prior page |

**Example request**

```bash
curl "https://api.cradlepointecm.com/api/v3/modem_software_versions" \
  -H "Authorization: Bearer <token>"
```

**Response 200** — Success

Schema: `ModemSoftwareVersionResponse`

```json
{
  "links": {
    "first": "https://api.cradlepointecm.com/api/v3/modem_software_versions?filter[group]=123&page[size]=20",
    "last": "https://api.cradlepointecm.com/api/v3/modem_software_versions?filter[group]=123&page[size]=20",
    "next": null,
    "prev": null
  },
  "data": [
    {
      "id": "string",
      "type": "modem_software_versions",
      "attributes": {
        "carrier": "string",
        "package_version": "string",
        "modem_type_name": "string",
        "min_router_version": "string"
      }
    }
  ]
}
```

**Response 204** — No Content - Could not find available modem packages

**Response 400** — Bad Request - Invalid parameters

**Response 403** — Forbidden - Request forbidden

### GET /api/v3/modem_upgrades

List modem upgrade jobs and activities

Return job and activities

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| filter[group] | query | integer | yes | Group ID to get all modem firmware upgrade jobs |
| filter[type] | query | string (modem_upgrade_parent | modem_upgrade_child) | yes | Type of resource to retrieve. Use 'modem_upgrade_parent' to list jobs for a group, 'modem_upgrade_child' to list activities for a specific job (requires filter[modem_upgrade_parent]) |
| filter[modem_upgrade_parent] | query | string | no | Parent job ID (required when filter[type]=modem_upgrade_child) |
| page[size] | query | integer | no | Number of results to return per page (max 50, default 20) |
| page[after] | query | string | no | Cursor for next page |
| page[before] | query | string | no | Cursor for prior page |

**Example request**

```bash
curl "https://api.cradlepointecm.com/api/v3/modem_upgrades" \
  -H "Authorization: Bearer <token>"
```

**Response 200** — Success

Schema: `ModemUpgradeResponse`

```json
{
  "links": {
    "first": "https://api.cradlepointecm.com/api/v3/modem_upgrades?filter[group]=123&filter[type]=modem_upgrade_parent&page[size]=20",
    "last": "https://api.cradlepointecm.com/api/v3/modem_upgrades?filter[group]=123&filter[type]=modem_upgrade_parent&page[size]=20",
    "next": null,
    "prev": null
  },
  "data": [
    {
      "type": "modem_upgrade_parent",
      "id": "string",
      "attributes": {
        "carrier": "string",
        "overwrite": false,
        "operation": "upgrade",
        "package_version": "string",
        "modem_count": 0,
        "success_count": 0,
        "failed_count": 0,
        "status": "created",
        "modem_type_name": "string",
        "connection_states": [
          "connected"
        ],
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      },
      "relationships": {
        "group": {
          "data": [
            {
              "type": "groups",
              "id": "string"
            }
          ]
        }
      }
    }
  ]
}
```

**Response 204** — No Content - No jobs or activities found

**Response 400** — Bad Request - Invalid parameters

**Response 403** — Forbidden - Request forbidden

### POST /api/v3/modem_upgrades

Execute a modem firmware upgrade job, with the capability of a preview option

Execute a modem firmware upgrade job

**Request body**

Schema: `ModemUpgradeRequest`

```json
{
  "data": {
    "type": "modem_upgrades",
    "attributes": {
      "carrier": "string",
      "modem_type_name": "string",
      "operation": "preview",
      "overwrite": false,
      "connection_states": [
        "connected"
      ]
    },
    "relationships": {
      "group": {
        "data": {
          "type": "groups",
          "id": "string"
        }
      }
    }
  }
}
```

**Example request**

```bash
curl -X POST "https://api.cradlepointecm.com/api/v3/modem_upgrades" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"data":{"type":"modem_upgrades","attributes":{"carrier":"string","modem_type_name":"string","operation":"preview","overwrite":false,"connection_states":["connected"]},"relationships":{"group":{"data":{"type":"groups","id":"string"}}}}}'
```

**Response 201** — Created

Schema: `ModemUpgradeResource`

**Response 400** — Bad Request - Invalid request body or parameters

**Response 403** — Forbidden - Request forbidden

### PUT /api/v3/modem_upgrades/{id}

Update a current modem firmware upgrade job

Modify a firmware upgrade job

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | yes | Job ID to update |

**Request body**

Schema: `ModemUpgradeRequest`

**Example request**

```bash
curl -X PUT "https://api.cradlepointecm.com/api/v3/modem_upgrades/{id}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

**Response 200** — Updated

Schema: `ModemUpgradeResource`

**Response 400** — Bad Request - Invalid request body or parameters

**Response 403** — Forbidden - Request forbidden

**Response 404** — Not Found - Job ID does not exist