Skip to content

Get peripherals

GET/settings/peripheral-control/peripherals

Endpoint API · Peripheral Control

Get all peripherals.

Required permissionendpoint-state:read

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.
page query integer No The page number to fetch, starting with 1.
pageSize query integer No The size of the page requested.
pageTotal query boolean No Whether the number of pages should be calculated and returned in the response.
lastSeenAfter query string No Find peripherals that were last seen after the given date and time (UTC) or a duration relative to the current date and time (inclusive).
Must be at most 24 characters long.
lastSeenBefore query string No Find peripherals that were last seen strictly before the given date and time (UTC) or a duration relative to the current date and time. Peripherals last seen exactly at the specified time are excluded.
Must be at most 24 characters long.
type query array of string No One or more peripheral types to include.
Each item must be one of: opticalDrive, floppyDrive, modem, encryptedStorage, infrared, wireless, removableStorage, bluetooth, mtp, camera.

Request samples

curl -X GET "https://api-<data-region>.central.sophos.com/endpoint/v1/settings/peripheral-control/peripherals" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>"


import requests

response = requests.get(
    "https://api-<data-region>.central.sophos.com/endpoint/v1/settings/peripheral-control/peripherals",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
    },
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
}
Invoke-RestMethod -Method GET -Uri "https://api-<data-region>.central.sophos.com/endpoint/v1/settings/peripheral-control/peripherals" -Headers $headers


package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, err := http.NewRequest("GET", "https://api-<data-region>.central.sophos.com/endpoint/v1/settings/peripheral-control/peripherals", nil)
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}


const response = await fetch("https://api-<data-region>.central.sophos.com/endpoint/v1/settings/peripheral-control/peripherals", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
  },
});
const data = await response.json();
console.log(data);

Responses

200 — List of peripherals.

Response fields

itemsarray of objectrequired
Array of peripherals objects.
Peripheral.
Show child attributesHide child attributes
idstring (uuid)required
Universally unique peripheral ID assigned by Sophos Central.
typestringrequired
Peripheral type.
Must be one of: opticalDrive, floppyDrive, modem, encryptedStorage, infrared, wireless, removableStorage, bluetooth, mtp, camera.
categorystringrequired
Peripheral category.
Must be one of: storage, network, media.
modelstringrequired
Peripheral model as reported by the associated endpoint.
Must be at most 250 characters long.
modelIdstringrequired
Peripheral model ID as reported by the associated endpoint.
Must be at most 250 characters long.
instanceIdstring
Peripheral instance ID as reported by the associated endpoint.
Must be at most 250 characters long.
lastEndpointobject
Reference to an endpoint.
Show child attributesHide child attributes
idstring (uuid)required
Unique endpoint ID.
hostnamestring
Endpoint hostname.
lastUsedBystring
Name or login of last known user of this peripheral, if available.
Must be at most 100 characters long.
lastActionTakenstring
Peripheral control action.
Must be one of: alertedOnly, readOnly, blocked.
firstSeenAtstring (date-time)
When this peripheral was first detected.
lastSeenAtstring (date-time)
When this peripheral was last detected.
pagesobjectrequired
Show child attributesHide child attributes
currentintegerrequired
The 1-based page number being returned.
sizeintegerrequired
The size of the page being returned.
totalinteger
(Optional) The total number of pages that exist, if pageTotal=true in the request.
itemsinteger
(Optional) The total number of items across all pages.
maxSizeintegerrequired
The maximum page size that can be requested.

Errors

Status Meaning
500 Unexpected error.

All error responses share the same shape — see the error response object.

Response examples

200

{
  "items": [
    {
      "id": "eb6c74a0-8bc2-4b88-9030-b547db0f2832",
      "type": "wireless",
      "category": "network",
      "model": "Apple Wireless Network Adapter (802.11 a\u2215b\u2215g\u2215n\u2215ac)",
      "modelId": "5AC-AIRPORT-19910ED94C48",
      "instanceId": "INS:5AC-AIRPORT-19910ED94C48",
      "lastEndpointHostname": "John's iMac",
      "lastUsedBy": "John's iMac\\johndoe",
      "lastActionTaken": "allowed",
      "firstSeenAt": "2020-10-29T11:03:57.000Z",
      "lastSeenAt": "2021-01-17T16:00:06.000Z"
    }
  ],
  "pages": {
    "current": 0,
    "size": 0,
    "total": 0,
    "items": 0,
    "maxSize": 0
  }
}

See the guide for a narrative walkthrough of this API.