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/off/

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.

To add or remove tags without replacing each device’s existing tags, use the optional add and remove fields instead of fields.tags. Each takes an object with a non-empty tags array. Tags in add are applied before tags in remove. add and remove can be combined with other fields, but not with fields.tags.

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 devices 5 and 286, adding the tags foo and bar and removing the tag baz. Any other tags are left unchanged.

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

{
    "devices": [
        {"id": "5"},
        {"id": "286"}
    ],
    "add": {
        "tags": [
            "foo",
            "bar"
        ]
    },
    "remove": {
        "tags": [
            "baz"
        ]
    }
}

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