Devices

List devices

Get a list of devices.

GET /api/v1/devices/{?page,limit,filter,sort}

URL Parameters

Name Description
page integer (optional) See Paging
limit integer (optional) See Paging
detailed boolean (optional) See Summary / Detailed Representations
filter string (optional) See Filtering
sort string (optional) See Sorting

Response 200 OK

{
    "timestamp": "2016-05-25T10:54:10.582786586-04:00",
    "data": [
        {
            "id": "21",
            "name": "Device Foo",
            "created": "2016-05-25T10:43:24.746428-04:00",
            "updated": "2016-05-25T10:45:22.926267-04:00",
            "locked": false,
            "user_id": "1",
            "picture_id": "21",
            "tags": [],
            "description": ""
        },
        {
            "id": "1",
            "name": "Device Bar",
            "created": "2016-05-24T12:35:21.917593-04:00",
            "updated": "2016-05-24T14:05:48.952095-04:00",
            "locked": false,
            "user_id": "1",
            "picture_id": "4",
            "tags": [],
            "description": ""
        },
        {
            "id": "12",
            "name": "Device Baz",
            "created": "2016-05-24T13:22:21.998464-04:00",
            "updated": "2016-05-25T10:25:52.055819-04:00",
            "locked": false,
            "user_id": "1",
            "picture_id": "19",
            "tags": [
                "one"
            ],
            "description": ""
        }
    ],
    "links": {
        "current": 1,
        "first": 1,
        "last": 1,
        "limit": 10,
        "total": 3
    }
}

Get a device

Get a device.

GET /api/v1/devices/{id}/

Response 200 OK

{
    "timestamp": "2016-05-25T10:56:49.279371686-04:00",
    "data": {
        "id": "12",
        "name": "Device Baz",
        "created": "2016-05-24T13:22:21.998464-04:00",
        "updated": "2016-05-25T10:25:52.055819-04:00",
        "locked": false,
        "user_id": "1",
        "attachments_dir": "/usr/cdrouter-data/attachments/12",
        "picture_id": "19",
        "tags": [
            "one"
        ],
        "default_ip": "192.168.178.1",
        "default_login": "qacafe",
        "default_password": "qacafe1234",
        "default_ssid": "qacafe",
        "location": "John's desk",
        "device_category": "wireless router",
        "manufacturer": "Foo Co",
        "manufacturer_oui": "",
        "model_name": "Foo-123",
        "model_number": "123",
        "description": "Foo Co Foo 123",
        "product_class": "",
        "serial_number": "0005678",
        "hardware_version": "1",
        "software_version": "",
        "provisioning_code": "",
        "note": "This is a wifi gateway with a DSL WAN port."
    }
}

Response 404 Not Found

{
    "error": "no such device"
}

Create a device

Create a new device.

POST /api/v1/devices/

Example

{
    "name": "Device Baz2",
    "user_id": "1",
    "tags": [
        "one",
        "three",
        "two"
    ],
    "default_ip": "192.168.1.1",
    "default_login": "admin",
    "default_password": "admin",
    "default_ssid": "qacafe",
    "location": "Rack 7",
    "description": "Baz2 router",
    "product_class": "",
    "serial_number": "",
    "hardware_version": "",
    "software_version": "",
    "provisioning_code": "",
    "note": ""
}

Response 200 OK

{
    "timestamp": "2016-05-25T10:58:39.816039365-04:00",
    "data": {
        "id": "22",
        "name": "Device Baz2",
        "created": "2016-05-25T10:58:39.792938857-04:00",
        "updated": "2016-05-25T10:58:39.793886912-04:00",
        "locked": false,
        "user_id": "1",
        "attachments_dir": "/usr/cdrouter-data/attachments/22",
        "picture_id": "0",
        "tags": [
            "one",
            "three",
            "two"
        ],
        "default_ip": "192.168.1.1",
        "default_login": "admin",
        "default_password": "admin",
        "default_ssid": "qacafe",
        "location": "Rack 7",
        "device_category": "",
        "manufacturer": "",
        "manufacturer_oui": "",
        "model_name": "",
        "model_number": "",
        "description": "Baz2 router",
        "product_class": "",
        "serial_number": "",
        "hardware_version": "",
        "software_version": "",
        "provisioning_code": "",
        "note": ""
    }
}

Edit a device

Edit a device.

PATCH /api/v1/devices/{id}/

Example

PATCH /api/v1/devices/123/

{
    "name": "Device Baz22",
    "user_id": "1",
    "tags": [
        "one",
        "three",
        "two"
    ],
    "default_ip": "192.168.1.1",
    "default_login": "admin",
    "default_password": "admin",
    "default_ssid": "qacafe",
    "location": "Rack 7",
    "description": "Baz2 router",
    "product_class": "",
    "serial_number": "",
    "hardware_version": "",
    "software_version": "",
    "provisioning_code": "",
    "note": ""
}

Response 200 OK

{
    "timestamp": "2016-05-25T10:58:39.816039365-04:00",
    "data": {
        "id": "22",
        "name": "Device Baz22",
        "created": "2016-05-25T10:58:39.792938857-04:00",
        "updated": "2016-05-25T10:58:39.793886912-04:00",
        "locked": false,
        "user_id": "1",
        "attachments_dir": "/usr/cdrouter-data/attachments/22",
        "picture_id": "0",
        "tags": [
            "one",
            "three",
            "two"
        ],
        "default_ip": "192.168.1.1",
        "default_login": "admin",
        "default_password": "admin",
        "default_ssid": "qacafe",
        "location": "Rack 7",
        "device_category": "",
        "manufacturer": "",
        "manufacturer_oui": "",
        "model_name": "",
        "model_number": "",
        "description": "Baz2 router",
        "product_class": "",
        "serial_number": "",
        "hardware_version": "",
        "software_version": "",
        "provisioning_code": "",
        "note": ""
    }
}

Delete a device

Delete a device.

DELETE /api/v1/devices/{id}/

Response 204 No Content

Lock a device

Lock a device. Locking a device prevents it from being modified or deleted until it is unlocked.

POST /api/v1/devices/{id}/lock

Response 200 OK

{
  "timestamp": "2023-03-29T15:42:10.757821652-04:00",
  "data": {
    "id": "1",
    "name": "Device Foo",
    "created": "2019-05-09T09:28:41.231124-04:00",
    "updated": "2023-03-29T15:42:10.753951602-04:00",
    "locked": true,
    "user_id": "1",
    "attachments_dir": "/usr/cdrouter-data/attachments/1",
    "picture_id": "5",
    "tags": [],
    "default_ip": "192.168.1.1",
    "default_login": "admin",
    "default_password": "qacafe123",
    "default_ssid": "",
    "location": "foo.lan",
    "device_category": "",
    "manufacturer": "",
    "manufacturer_oui": "",
    "model_name": "",
    "model_number": "",
    "description": "foo bar",
    "product_class": "",
    "serial_number": "",
    "hardware_version": "",
    "software_version": "",
    "provisioning_code": "",
    "note": "",
    "insecure_mgmt_url": false,
    "mgmt_url": "http://192.168.1.1",
    "add_mgmt_addr": true,
    "mgmt_interface": "wlo1",
    "mgmt_addr": "192.168.1.209/24",
    "power_on_cmd": "",
    "power_off_cmd": ""
  }
}

Unlock a device

Unlock a device. Unlocking a locked device allows it to be modified or deleted once again.

POST /api/v1/devices/{id}/unlock

Response 200 OK

{
  "timestamp": "2023-03-29T15:42:10.757821652-04:00",
  "data": {
    "id": "1",
    "name": "Device Foo",
    "created": "2019-05-09T09:28:41.231124-04:00",
    "updated": "2023-03-29T15:42:10.753951602-04:00",
    "locked": false,
    "user_id": "1",
    "attachments_dir": "/usr/cdrouter-data/attachments/1",
    "picture_id": "5",
    "tags": [],
    "default_ip": "192.168.1.1",
    "default_login": "admin",
    "default_password": "qacafe123",
    "default_ssid": "",
    "location": "foo.lan",
    "device_category": "",
    "manufacturer": "",
    "manufacturer_oui": "",
    "model_name": "",
    "model_number": "",
    "description": "foo bar",
    "product_class": "",
    "serial_number": "",
    "hardware_version": "",
    "software_version": "",
    "provisioning_code": "",
    "note": "",
    "insecure_mgmt_url": false,
    "mgmt_url": "http://192.168.1.1",
    "add_mgmt_addr": true,
    "mgmt_interface": "wlo1",
    "mgmt_addr": "192.168.1.209/24",
    "power_on_cmd": "",
    "power_off_cmd": ""
  }
}

Get a device’s shares

Get shares for a device.

GET /api/v1/devices/{id}/shares

Response 200 OK

{
    "timestamp": "2016-04-15T10:00:22.32676552-04:00",
    "data": [
        {
            "user_id": "307",
            "read": true,
            "write": false,
            "execute": false
        },
        {
            "user_id": "309",
            "read": true,
            "write": false,
            "execute": false
        }
    ]
}

Edit a device’s shares

Edit shares for a device.

PATCH /api/v1/devices/{id}/shares

Example

PATCH /api/v1/devices/123/shares

{
    "user_ids": [
        309,
        307
    ]
}

Response 200 OK

{
    "timestamp": "2016-04-15T10:00:22.32676552-04:00",
    "data": [
        {
            "user_id": "309",
            "read": true,
            "write": false,
            "execute": false
        },
        {
            "user_id": "307",
            "read": true,
            "write": false,
            "execute": false
        }
    ]
}

Export a device

Export a device.

GET /api/v1/devices/{id}/?format=gz

Response 200 OK

Content-Type: application/x-gzip
Content-Disposition: inline; filename="{name}.gz"

Get a device’s connection

Get information on proxy connection to device’s management interface.

GET /api/v1/devices/{id}/connect/

Response 200 OK

{
    "timestamp": "2016-04-15T10:00:22.32676552-04:00",
    "data": {
        "proxy_port": 49870,
        "proxy_https": 49872
    }
}

Connect to a device

Open proxy connection to a device’s management interface.

POST /api/v1/devices/{id}/connect/

Response 200 OK

{
    "timestamp": "2016-04-15T10:00:22.32676552-04:00",
    "data": {
        "proxy_port": 49870,
        "proxy_https": 49872
    }
}

Disconnect from a device

Close proxy connection to a device’s management interface.

POST /api/v1/devices/{id}/disconnect/

Response 204 No Content

Power on a device

Power on a device using it’s power on command.

POST /api/v1/devices/{id}/power/on/

Response 200 OK

{
    "timestamp": "2016-04-15T10:00:22.32676552-04:00",
    "data": {
        "output": "<output-from-command...>"
    }
}

Power off a device

This endpoint was introduced in CDRouter 10.3 and is not available in previous releases of CDRouter.

Power off a device using it’s power off command.

POST /api/v1/devices/{id}/power/on/

Response 200 OK

{
    "timestamp": "2016-04-15T10:00:22.32676552-04:00",
    "data": {
        "output": "<output-from-command...>"
    }
}

Bulk export devices

Bulk export a set of devices.

GET /api/v1/devices/{?bulk=export,ids}

URL Parameters

Name Description
bulk string (required) Must be export
ids string (required) Comma-separated device IDs to export

Example

GET /api/v1/devices/?bulk=export&ids=123,456,789

Response 200 OK

Content-Type: application/x-gzip
Content-Disposition: inline; filename="devices-{timestamp}.gz"

Bulk copy devices

Bulk copy a set of devices.

POST /api/v1/devices/?bulk=copy

Example

POST /api/v1/devices/?bulk=copy

{
    "devices": [
        {"id": "1"},
        {"id": "12"}
    ]
}

Response 200 OK

Returns devices array containing new devices copied from input IDs.

{
    "timestamp": "2016-05-25T11:01:56.470162552-04:00",
    "data": [
        {
            "id": "23",
            "name": "Device Foo (copy 1)",
            "created": "2016-05-24T12:35:21.917593-04:00",
            "updated": "2016-05-25T11:01:56.438313518-04:00",
            "locked": false,
            "user_id": "1",
            "attachments_dir": "/usr/cdrouter-data/attachments/23",
            "picture_id": "22",
            "tags": [],
            "default_ip": "192.168.1.1",
            "default_login": "admin",
            "default_password": "admin",
            "default_ssid": "qacafe",
            "location": "Rack 7",
            "device_category": "",
            "manufacturer": "",
            "manufacturer_oui": "",
            "model_name": "",
            "model_number": "",
            "description": "",
            "product_class": "",
            "serial_number": "",
            "hardware_version": "3.4",
            "software_version": "",
            "provisioning_code": "",
            "note": ""
        },
        {
            "id": "24",
            "name": "Device Bar (copy 1)",
            "created": "2016-05-24T13:22:21.998464-04:00",
            "updated": "2016-05-25T11:01:56.447127497-04:00",
            "locked": false,
            "user_id": "1",
            "attachments_dir": "/usr/cdrouter-data/attachments/24",
            "picture_id": "27",
            "tags": [
                "one"
            ],
            "default_ip": "192.168.178.1",
            "default_login": "qacafe",
            "default_password": "qacafe1234",
            "default_ssid": "qacafe",
            "location": "John's desk",
            "device_category": "wireless router",
            "manufacturer": "Bar Co",
            "manufacturer_oui": "",
            "model_name": "Bar",
            "model_number": "123",
            "description": "Bar Co 123",
            "product_class": "",
            "serial_number": "0005678",
            "hardware_version": "1",
            "software_version": "",
            "provisioning_code": "",
            "note": "This is a wifi gateway with a DSL WAN port."
        }
    ]
}

Bulk edit devices

Bulk edit a set of devices.

POST /api/v1/devices/{?bulk=edit,filter,all}

URL Parameters

Name Description
bulk string (required) Must be edit
filter string (optional) See Filtering
all boolean (optional) If true, apply edits to all devices.

Example

Bulk edit devices 5 and 286, setting their user_id field to 3 and tags field to ["foo", "bar", "baz"].

POST /api/v1/devices/?bulk=edit

{
    "devices": [
        {"id": "5"},
        {"id": "286"}
    ],
    "fields": {
        "user_id": "3",
        "tags": [
            "foo",
            "bar",
            "baz"
        ]
    }
}

Bulk edit devices matching filters user_id=3 and software_version=1.2, setting their tags field to ["1.2"].

POST /api/v1/devices/?bulk=edit&filter=user_id=3&filter=software_version=1.2

{
    "fields": {
        "tags": [
            "1.2"
        ]
    }
}

Bulk edit all devices, setting their user_id field to 3.

POST /api/v1/devices/?bulk=edit&all=true

{
    "fields": {
        "user_id": "3"
    }
}

Response 204 No Content

Bulk delete devices

Bulk delete a set of devices.

POST /api/v1/devices/{?bulk=delete,filter,all}

URL Parameters

Name Description
bulk string (required) Must be delete
filter string (optional) See Filtering
all boolean (optional) If true, delete all devices.

Example

Bulk delete devices 5 and 286.

POST /api/v1/devices/?bulk=delete

{
    "devices": [
        {"id": "5"},
        {"id": "286"}
    ]
}

Bulk delete devices matching filters user_id=3 and software_version=1.2.

POST /api/v1/devices/?bulk=delete&filter=user_id=3&filter=software_version=1.2

Bulk delete all devices.

POST /api/v1/devices/?bulk=delete&all=true

Response 204 No Content

List a device’s attachments

Get a list of a device’s attachments.

GET /api/v1/devices/{id}/attachments/{?page,limit,filter,sort}

URL Parameters

Name Description
page integer (optional) See Paging
limit integer (optional) See Paging
detailed boolean (optional) See Summary / Detailed Representations
filter string (optional) See Filtering
sort string (optional) See Sorting

Response 200 OK

{
    "timestamp": "2016-05-25T11:13:22.072227509-04:00",
    "data": [
        {
            "id": "16",
            "name": "32145084-2-440-back-4.gif",
            "created": "2016-05-25T09:39:39.801002-04:00",
            "updated": "2016-05-25T09:39:39.801002-04:00",
            "size": 76314,
            "device_id": "1"
        },
        {
            "id": "4",
            "name": "front20131010123406.png",
            "created": "2016-05-24T12:42:10.811008-04:00",
            "updated": "2016-05-24T12:42:10.811008-04:00",
            "size": 64852,
            "device_id": "1"
        },
        {
            "id": "17",
            "name": "error.log",
            "created": "2016-05-25T09:50:29.338772-04:00",
            "updated": "2016-05-25T09:50:29.338772-04:00",
            "size": 14,
            "device_id": "1"
        },
        {
            "id": "18",
            "name": "log_2.txt",
            "created": "2016-05-25T09:59:58.492047-04:00",
            "updated": "2016-05-25T09:59:58.492047-04:00",
            "size": 4845,
            "device_id": "1"
        }
    ],
    "links": {
        "current": 1,
        "first": 1,
        "last": 1,
        "limit": 13,
        "total": 13
    }
}

Get a device’s attachment

Get a device’s attachment.

GET /api/v1/devices/{id}/attachments/{attid}/

Response 200 OK

{
    "timestamp": "2016-05-25T11:14:22.581326968-04:00",
    "data": {
        "id": "16",
        "name": "32145084-2-440-back-4.gif",
        "created": "2016-05-25T09:39:39.801002-04:00",
        "updated": "2016-05-25T09:39:39.801002-04:00",
        "size": 76314,
        "path": "/usr/cdrouter-data/attachments/1/32145084-2-440-back-4.gif",
        "device_id": "1"
    }
}

Response 404 Not Found

{
    "error": "no such attachment"
}

Create a device attachment

Add an attachment to a device.

POST /api/v1/devices/{id}/attachments/

Example

Request must have a Content-Type header of multipart/form-data. The request body must have a form key named file with a filename parameter. The contents of the form key must be the file attachment.

POST /api/v1/devices/1/attachments/
Content-Type: multipart/form-data; boundary=----CBacgHmUVPwTniJL

----CBacgHmUVPwTniJL
Content-Disposition: form-data; name="file"; filename="image.png"
Content-Type: image/png


<attachment contents...>
----CBacgHmUVPwTniJL--

Response 200 OK

{
    "timestamp": "2016-05-25T11:17:15.240904436-04:00",
    "data": {
        "id": "28",
        "name": "image.png",
        "created": "2016-05-25T11:17:15.220010745-04:00",
        "updated": "2016-05-25T11:17:15.220010745-04:00",
        "size": 734546,
        "path": "/usr/cdrouter-data/attachments/1/image.png",
        "device_id": "1"
    }
}

Download a device’s attachment

Download a device’s attachment.

GET /api/v1/devices/{id}/attachments/{attid}/?format=download

Response 200 OK

Content-Disposition: inline; filename="{name}"

Response 404 Not Found

{
    "error": "no such attachment"
}

Download thumbnail of a device’s attachment

Download thumbnail of a device’s attachment. Attachment must be a GIF, JPEG or PNG image.

GET /api/v1/devices/{id}/attachments/{attid}/{?format=thumbnail,size}

URL Parameters

Name Description
format string (required) Must be thumbnail
size integer (optional) Thumbnail height Default: 25

Response 200 OK

Content-Disposition: inline; filename="{name}-thumbnail-{size}px"

Response 404 Not Found

{
    "error": "no such attachment"
}

Edit a device’s attachment

Edit a device’s attachment.

PATCH /api/v1/devices/{id}/attachments/{attid}/

Example

PATCH /api/v1/devices/22/attachments/16/

{
    "name": "front-image.png"
}

Response 200 OK

{
    "timestamp": "2016-05-25T11:14:22.581326968-04:00",
    "data": {
        "id": "16",
        "name": "front-image.png",
        "created": "2016-05-25T09:39:39.801002-04:00",
        "updated": "2016-05-25T09:39:39.801002-04:00",
        "size": 76314,
        "path": "/usr/cdrouter-data/attachments/1/32145084-2-440-back-4.gif",
        "device_id": "1"
    }
}

Delete a device’s attachment

Delete a device’s attachment.

DELETE /api/v1/devices/{id}/attachments/{attid}/

Response 204 No Content