Platform REST API Reference

WARNING: This is a legacy document, please view the latest version here.

This API will be deactivated on September 5, 2024.

The integrationServices/v3/devices API has been deprecated and replaced by the platform Devices v6 API

Migration information is available in the Migration Guide.

API Basics

The Endpoint Standard API is accessible through a special hostname assigned to your organization. To find your organization’s API hostname, please refer to this the Authentication Guide. Once you receive the API hostname, the following API routes are accessible through the integrationServices path on your API host.

Authentication is handled by an API key and Connector ID, which is generated from the Connectors page of the Endpoint Standard console. The API key and Connector ID are concatenated together to form the X-Auth-Token HTTP header, which is used to control access to the Endpoint Standard API. For more information on generating the API token and the HTTP header, see the Endpoint Standard API authentication reference.

For example, to use the “Device” endpoint assuming that your API hostname is defense.conferdeploy.net, you would use the following curl command:

$ curl -H X-Auth-Token:ABCD/1234 \
https://defense.conferdeploy.net/integrationServices/v3/device

Pagination

Most APIs are paginated so that large result sets can be returned back to your API client in chunks. Every paginated API has the same standard request and response template.

When using a paginated API, the request includes two optional query parameters: start and rows. The start query parameter indicates the first row number that the API client expects from the result, and rows indicates the maximum number of rows that the API client expects in the response. Note that the maximum value of the rows parameter can be limited on the Endpoint Standard server side. The start value is based on a one-index. To retrieve the first 10 results of a result set, use start=1&rows=10.

The response payload also includes a totalResults value that indicates the total number of objects that matched the query.

Response Codes

  • HTTP 200: Successful response
  • HTTP 400: Bad request. Check the messages response for more information on errors encountered parsing the incoming payload.
  • HTTP 401: Unauthorized. Double check the X-Auth-Token authentication HTTP header to make sure that the Connector ID and API key are valid.
  • HTTP 404: Object not found. The requested object could not be found in the backend data store or it may have expired (over 30 days old, etc.)
  • HTTP 429: Rate limiting encountered. Try again in a minute.
  • HTTP 500: Internal server error. Check the messages response for more information.
  • In addition, each message returns a boolean success indicator that indicates whether the operation was successful. The response contents should be further examined or processed only if the success indicator is true.

Devices

The integrationServices/v3/devices API has been deprecated and replaced by the platform Devices v6 API

Migration information is available in the Migration Guide.

Devices API allows consumers to query enrollment data to view status & details of devices in their organization. Only API keys of type “API” can call the devices API.

Bulk Sensor Data Retrieval

GET /integrationServices/v3/device/all?fileFormat=<option>

This single request will retrieve all Endpoint Standard Sensor Details in either CSV or JSON format. There is currently a limitation of 100k records even using this new API call. Without using the above API calls there is a hard limit of 5k rows per call built into the API even using pagination parameters, and a maximum of 15k records can be returned.

This request has one mandatory parameter:

  • fileFormat: This can be set to ‘csv’ or ‘json’ for the corresponding format type.

Example Request & Response:

  • Request (application/json)

      $ curl -H X-Auth-Token:<apikey>/<connectorid> https://defense.conferdeploy.net/integrationServices/v3/device/all?fileFormat=json

  • Response 200 (application/json) 

    {
  "latestTime" : 0,
  "success" : true,
  "message" : "Success",
  "totalResults" : 8,
  "elapsed" : 0,
  "results" : [ {
    "emailAddress" : "bs@carbonblack.com",
    "quarantined" : null,
    "policyName" : "default",
    "deregistered" : "deregistered",
    "wrapperAsCsvString" : "BSTURK-WIN7-X86,bs@carbonblack.com,default,WINDOWS,2.0.1.8,null,20170313,114037,deregistered,20170313,null,null,null,null",
    "deviceName" : "BSTURK-WIN7-X86",
    "sensorVersion" : "2.0.1.8",
    "deregisteredDate" : "20170313",
    "bypassed" : null,
    "quarantinedDate" : null,
    "bypassedDate" : null,
    "os" : "WINDOWS",
    "outofDate" : null,
    "lastCheckInDate" : "20170313",
    "lastCheckInTime" : "114037"
  }, {
    "emailAddress" : "MarketingVP2-PC\\MarketingVP2",
    "quarantined" : null,
    "policyName" : "Restrictive_Windows_Workstation",
    "deregistered" : null,
    "wrapperAsCsvString" : "MarketingVP2-PC,MarketingVP2-PC\\MarketingVP2,Restrictive_Windows_Workstation,WINDOWS,2.0.1.6,null,20161206,221058,null,null,null,null,null,null",
    "deviceName" : "MarketingVP2-PC",
    "sensorVersion" : "2.0.1.6",
    "deregisteredDate" : null,
    "bypassed" : null,
    "quarantinedDate" : null,
    "bypassedDate" : null,
    "os" : "WINDOWS",
    "outofDate" : null,
    "lastCheckInDate" : "20161206",
    "lastCheckInTime" : "221058"
  }, {
    "emailAddress" : "MarketingVP2-PC\\MarketingVP2",
    "quarantined" : null,
    "policyName" : "Restrictive_Windows_Workstation",
    "deregistered" : "deregistered",
    "wrapperAsCsvString" : "MarketingVP2-PC,MarketingVP2-PC\\MarketingVP2,Restrictive_Windows_Workstation,WINDOWS,null,null,20161205,205658,deregistered,20161205,null,null,null,null",
    "deviceName" : "MarketingVP2-PC",
    "sensorVersion" : null,
    "deregisteredDate" : "20161205",
    "bypassed" : null,
    "quarantinedDate" : null,
    "bypassedDate" : null,
    "os" : "WINDOWS",
    "outofDate" : null,
    "lastCheckInDate" : "20161205",
    "lastCheckInTime" : "205658"
  }, {
    "emailAddress" : "em@carbonblack.com",
    "quarantined" : null,
    "policyName" : "Restrictive_Windows_Workstation",
    "deregistered" : null,
    "wrapperAsCsvString" : "WIN-1PU82PIDOO6,em@carbonblack.com,Restrictive_Windows_Workstation,WINDOWS,2.0.1.2,out_of_date,20170627,162925,null,null,null,null,null,null",
    "deviceName" : "WIN-1PU82PIDOO6",
    "sensorVersion" : "2.0.1.2",
    "deregisteredDate" : null,
    "bypassed" : null,
    "quarantinedDate" : null,
    "bypassedDate" : null,
    "os" : "WINDOWS",
    "outofDate" : "out_of_date",
    "lastCheckInDate" : "20170627",
    "lastCheckInTime" : "162925"
  }, {
    "emailAddress" : "WIN-4G298B12C5D\\Trusting Tom",
    "quarantined" : null,
    "policyName" : "default",
    "deregistered" : "deregistered",
    "wrapperAsCsvString" : "WIN-4G298B12C5D,WIN-4G298B12C5D\\Trusting Tom,default,WINDOWS,2.0.4.9,null,20170630,172520,deregistered,20170714,null,null,null,null",
    "deviceName" : "WIN-4G298B12C5D",
    "sensorVersion" : "2.0.4.9",
    "deregisteredDate" : "20170714",
    "bypassed" : null,
    "quarantinedDate" : null,
    "bypassedDate" : null,
    "os" : "WINDOWS",
    "outofDate" : null,
    "lastCheckInDate" : "20170630",
    "lastCheckInTime" : "172520"
  }, {
    "emailAddress" : "WIN-4G298B12C5D\\Trusting Tom",
    "quarantined" : null,
    "policyName" : "Live Response Enabled",
    "deregistered" : null,
    "wrapperAsCsvString" : "WIN-4G298B12C5D,WIN-4G298B12C5D\\Trusting Tom,Live Response Enabled,WINDOWS,3.0.0.28,null,20170714,181814,null,null,null,null,null,null",
    "deviceName" : "WIN-4G298B12C5D",
    "sensorVersion" : "3.0.0.28",
    "deregisteredDate" : null,
    "bypassed" : null,
    "quarantinedDate" : null,
    "bypassedDate" : null,
    "os" : "WINDOWS",
    "outofDate" : null,
    "lastCheckInDate" : "20170714",
    "lastCheckInTime" : "181814"
  }, {
    "emailAddress" : "sq@carbonblack.com",
    "quarantined" : null,
    "policyName" : "SE Demo",
    "deregistered" : "deregistered",
    "wrapperAsCsvString" : "WIN-559J1NQVFGJ,sq@carbonblack.com,SE Demo,WINDOWS,null,null,20171012,161758,deregistered,20171012,null,null,null,null",
    "deviceName" : "WIN-559J1NQVFGJ",
    "sensorVersion" : null,
    "deregisteredDate" : "20171012",
    "bypassed" : null,
    "quarantinedDate" : null,
    "bypassedDate" : null,
    "os" : "WINDOWS",
    "outofDate" : null,
    "lastCheckInDate" : "20171012",
    "lastCheckInTime" : "161758"
  }, {
    "emailAddress" : "EDTESTING\\Trusting Tom",
    "quarantined" : null,
    "policyName" : "Live Response Enabled",
    "deregistered" : null,
    "wrapperAsCsvString" : "EDTESTING,EDTESTING\\Trusting Tom,Live Response Enabled,WINDOWS,3.0.2.2,null,20180117,133018,null,null,null,null,null,null",
    "deviceName" : "EDTESTING",
    "sensorVersion" : "3.0.2.2",
    "deregisteredDate" : null,
    "bypassed" : null,
    "quarantinedDate" : null,
    "bypassedDate" : null,
    "os" : "WINDOWS",
    "outofDate" : null,
    "lastCheckInDate" : "20180117",
    "lastCheckInTime" : "133018"
  } ]
}

Device Status

GET /integrationServices/v3/device

Get a status of all devices. The response will be in json format.

Optionally you can include a query parameter to filter the results. Combining these query parameters is an implicit “AND”. So, for example, querying for ipAddress=1.2.3.4 and hostName=ABCD will only return devices that match both the IP address and hostname query.

  • hostName: filter on hostnames based on a case insensitive token search. Endpoint Standard separates hostnames into parts or “tokens” defined by hyphens. So, for example, a hostname of WIN-IA9NQ1GN8OI will be parsed into two tokens: WIN and IA9NQ1GN8OI. Searching for either hostName=IA9NQ1GN8OI or hostname=win will match to the hostname WIN-IA9NQ1GN8OI.
  • hostNameExact: filter on the exact hostname. For example hostName=WIN-IA9NQ1GN8OI will only return devices with the exact hostname WIN-IA9NQ1GN8OI but not a host named win-IA9NQ1GN8OI
  • ownerName: filter on owner name case insensitively.
  • ownerNameExact: same as ownerName but with case sensitivity
  • ipAddress: filter on devices with a given external or internal IP address

Example Request & Response:

  • Request (application/json)

      $ curl -H X-Auth-Token:ABCD/1234 \
  https://defense.conferdeploy.net/integrationServices/v3/device

  • Response 200 (application/json) 

    {
  "latestTime" : 0,
  "success" : true,
  "message" : "Success",
  "totalResults" : 10,
  "elapsed" : 2,
  "results" : [ {
    "createTime" : null,
    "lastReportedTime" : 1490119807460,
    "deviceId" : 218616,
    "email" : "Administrator",
    "deviceType" : "WINDOWS",
    "targetPriorityType" : "HIGH",
    "organizationId" : 423,
    "avUpdateServers" : null,
    "avMaster" : false,
    "lastContact" : 1490128179664,
    "lastInternalIpAddress" : null,
    "lastExternalIpAddress" : "1.2.3.4",
    "lastLocation" : "OFFSITE",
    "quarantined" : false,
    "rootedBySensor" : false,
    "rootedBySensorTime" : null,
    "rootedByAnalytics" : false,
    "rootedByAnalyticsTime" : null,
    "firstVirusActivityTime" : 0,
    "lastVirusActivityTime" : 0,
    "organizationName" : "orgname.com",
    "osVersion" : "Server 2012 R2 x64 ",
    "sensorVersion" : "1.0.6.301",
    "deviceGuid" : null,
    "deviceOwnerId" : 58306,
    "deviceSessionId" : null,
    "assignedToId" : null,
    "assignedToName" : null,
    "messages" : null,
    "windowsPlatform" : null,
    "deregisteredTime" : null,
    "uninstalledTime" : null,
    "registeredTime" : 1489172152964,
    "firstName" : null,
    "lastName" : null,
    "middleName" : null,
    "policyName" : "Restrictive_Windows_Workstation",
    "policyId" : 2145,
    "activationCode" : null,
    "activationCodeExpiryTime" : 1489776952672,
    "lastShutdownTime" : 0,
    "lastResetTime" : 0,
    "sensorStates" : [ "ACTIVE" ],
    "vdiBaseDevice" : null,
    "passiveMode" : false,
    "testId" : -1,
    "scanStatus" : null,
    "scanLastActionTime" : 0,
    "scanLastCompleteTime" : 0,
    "linuxKernelVersion" : null,
    "avEngine" : "",
    "avStatus" : [ "AV_NOT_REGISTERED" ],
    "avLastScanTime" : 0,
    "name" : "WIN-EK5MJ5DQC3Q",
    "status" : "REGISTERED"
  }]
}

Get Status of Individual Device

GET /integrationServices/v3/device/{id}

Retrieve details for an individual device given the device ID (deviceId)

  • Request (application/json)

      $ curl -H X-Auth-Token:ABCD/1234 \
  https://defense.conferdeploy.net/integrationServices/v3/device/218616

  • Response 200 (application/json) 

    {"deviceInfo": {
    "createTime" : null,
    "lastReportedTime" : 1490119807460,
    "deviceId" : 218616,
    "email" : "Administrator",
    "deviceType" : "WINDOWS",
    "targetPriorityType" : "HIGH",
    "organizationId" : 423,
    "avUpdateServers" : null,
    "avMaster" : false,
    "lastContact" : 1490128179664,
    "lastInternalIpAddress" : null,
    "lastExternalIpAddress" : "1.2.3.4",
    "lastLocation" : "OFFSITE",
    "quarantined" : false,
    "rootedBySensor" : false,
    "rootedBySensorTime" : null,
    "rootedByAnalytics" : false,
    "rootedByAnalyticsTime" : null,
    "firstVirusActivityTime" : 0,
    "lastVirusActivityTime" : 0,
    "organizationName" : "orgname.com",
    "osVersion" : "Server 2012 R2 x64 ",
    "sensorVersion" : "1.0.6.301",
    "deviceGuid" : null,
    "deviceOwnerId" : 58306,
    "deviceSessionId" : null,
    "assignedToId" : null,
    "assignedToName" : null,
    "messages" : null,
    "windowsPlatform" : null,
    "deregisteredTime" : null,
    "uninstalledTime" : null,
    "registeredTime" : 1489172152964,
    "firstName" : null,
    "lastName" : null,
    "middleName" : null,
    "policyName" : "Restrictive_Windows_Workstation",
    "policyId" : 2145,
    "activationCode" : null,
    "activationCodeExpiryTime" : 1489776952672,
    "lastShutdownTime" : 0,
    "lastResetTime" : 0,
    "sensorStates" : [ "ACTIVE" ],
    "vdiBaseDevice" : null,
    "passiveMode" : false,
    "testId" : -1,
    "scanStatus" : null,
    "scanLastActionTime" : 0,
    "scanLastCompleteTime" : 0,
    "linuxKernelVersion" : null,
    "avEngine" : "",
    "avStatus" : [ "AV_NOT_REGISTERED" ],
    "avLastScanTime" : 0,
    "name" : "WIN-EK5MJ5DQC3Q",
    "status" : "REGISTERED",
  }
}

Change Status of an Individual Device

PATCH /integrationServices/v3/device/{id}

Change status of an individual device by its device ID (deviceId). The current revision of the Endpoint Standard backend only allows one element to be changed with this call: the security policy assigned to the device.

The requested security policy can be indicated either as a policy ID (policyId) or policy name (policyName).

  • Request (application/json)

      $ curl -X PATCH -H Content-Type:application/json \
  -H X-Auth-Token:ABCD/1234 \
  -d '{"policyName": "Restrictive_Windows_Workstation"}' \
  https://defense.conferdeploy.net/integrationServices/v3/device/4211

  • Response 200 

    {
  "deviceInfo" : {
    "avUpdateServers" : null,
    "avMaster" : false,
    "lastReportedTime" : 1497383068962,
    "lastContact" : 1497387645372,
    "lastInternalIpAddress" : "192.168.215.150",
    "lastExternalIpAddress" : "1.2.3.4",
    "lastLocation" : "OFFSITE",
    "quarantined" : false,
    "rootedBySensor" : false,
    "rootedBySensorTime" : null,
    "rootedByAnalytics" : false,
    "rootedByAnalyticsTime" : null,
    "firstVirusActivityTime" : 0,
    "lastVirusActivityTime" : 0,
    "organizationName" : "orgname.org",
    "osVersion" : "Windows 8 x64",
    "deviceType" : "WINDOWS",
    "sensorVersion" : "2.0.4.9",
    "email" : "jgarman@carbonblack.com",
    "deviceGuid" : null,
    "deviceOwnerId" : 70668,
    "deviceSessionId" : null,
    "assignedToId" : null,
    "assignedToName" : null,
    "messages" : null,
    "createTime" : null,
    "deviceId" : 4211,
    "targetPriorityType" : "LOW",
    "organizationId" : 428,
    "windowsPlatform" : null,
    "registeredTime" : 1493752696879,
    "firstName" : "Jason",
    "lastName" : "Garman",
    "middleName" : "",
    "activationCode" : "xxxxx",
    "lastShutdownTime" : 0,
    "lastResetTime" : 0,
    "sensorStates" : [ "ACTIVE" ],
    "vdiBaseDevice" : null,
    "passiveMode" : false,
    "testId" : -1,
    "scanStatus" : null,
    "scanLastActionTime" : 0,
    "scanLastCompleteTime" : 0,
    "linuxKernelVersion" : null,
    "avEngine" : "4.5.2.234-ave.8.3.44.86:avpack.8.4.2.64:vdf.8.14.11.240",
    "avStatus" : [ "AV_ACTIVE", "ONDEMAND_SCAN_DISABLED" ],
    "avLastScanTime" : 0,
    "sensorOutOfDate" : false,
    "name" : "WIN-IA9NQ1GN8OI",
    "status" : "REGISTERED",
    "id" : -1,
    "updateVersion" : 1322,
    "policyId" : 2202,
    "policyName" : "Restrictive_Windows_Workstation",
    "uninstalledTime" : null
  },
  "success" : true,
  "message" : "Success"
}


Last modified on March 17, 2022