Skip Navigation

Request a focus view

Request a focus view from a specified device.
Service endpoint
/foci/v2
Optional query string parameters
Example
https://protectapi.cylance.com/foci/v2
Method
HTTP/1.1 POST
Request headers
  • Accept: application/json
  • Authorization: Bearer
    JWT Token returned by Auth API
    with the opticsfocus:create scope encoded

Request

{ "device_id": "E378DACB9324453AB8C65A8406952195", "artifact_type": "Process", "artifact_subtype": "Uid", "value": "59F849F29BBE4F1F889AAF50F9153618", "threat_type": "THREAT", "description": "Focus View Example" }

Response

Please see the Response status codes for more information.

Request JSON schema

Field Name
Description
device_id
This is the unique device ID that the lockdown command was issued to. See About device ID for device ID formatting.
artifact_type
This is the type of artifact for the focus view.
  • Protect: Request a focus view for a
    BlackBerry Protect Desktop
    -generated event.
  • Process: Request a focus view for a process artifact to visualize how a process interacts with the device. This is the most common option.
  • File: Request a focus view for a file artifact to visualize how the file has been interacted with.
  • NetworkConnection: Request a focus view for a Network artifact to visualize communications associated with an IP address.
  • RegistryKey: Request a focus view for a registry artifact to visualize how the registry key or path has been interacted with.
artifact_subtype
This field should always be "Uid" at this time.
value
This is the UID of the artifact to gather a focus view about. This can be obtained from InstaQuery results, another focus view, the details/associated artifacts of a detection event, or anywhere else an artifact is referenced.
threat_type
This is an optional field to use with a "Protect" artifact_type to denote the type of threat that a focus view is being generated for.
description
This is the human-readable description for the focus view.

Response JSON schema

Field Name
Description
device_id
This is the unique device ID that the lockdown command was issued to. See About device ID for device ID formatting.
artifact_type
This is the type of artifact for the focus view.
  • Protect: Request a focus view for a
    BlackBerry Protect Desktop
    -generated event.
  • Process: Request a focus view for a process artifact to visualize how a process interacts with the device. This is the most common option.
  • File: Request a focus view for a file artifact to visualize how the file has been interacted with.
  • NetworkConnection: Request a focus view for a network artfiact to visualize communications associated with an IP address.
  • RegistryKey: Request a focus view for a registry artifact to visualize how the registry key or path has been interacted with.
artifact_subtype
This field should always be "Uid" at this time.
value
This is the UID of the artifact to gather a focus view about. This can be obtained from InstaQuery results, another focus view, the details/associated artifacts of a detection event, or anywhere else an artifact is referenced.
threat_type
This is an optional field to use with a "Protect" artifact_type to denote the type of threat that a focus view is being generated for.
description
This is the human-readable description for the focus view.
id
This is the unique ID of the focus view.
tenant_id
This is the unique ID of the tenant associated with the focus view.
create_at
This is the timestamp (in UTC) of when the focus view was created.
hostname
This is the hostname of the device that the focus view was requested from.
status
This is the status of the focus view result or request. Possible values are:
  • AVAILABLE: A focus view has been generated and is available for viewing.
  • PENDING: The focus view has been requested.
  • REQUEST: The focus view has not been generated, but it can be requested.
  • RETRY_REQUEST: The focus view has not been generated. It was previously requested but no results were received. It can be requested again.
  • DOES_NOT_EXIST: The focus view requested on the device cannot be completed because the requested parameters do not exist on the device.
  • UNAVAILABLE: The focus view is not available, and the associated device is not online to fulfill the request. It can be requested at a later time.
  • UNKNOWN_DEVICE: The focus view is not available, and the associated device is no longer known.
relations
This is a list of objects that are related to this focus view. The following fields can be contained:
  • Object: This is the URL of a focus view, InstaQuery, or detection event that is linked to this focus view.
  • Relationship: This shows how the relationship was established.