# Retrieve a custom detection

Returns one custom detection in full: its detection logic exactly as stored, and every rule and its settings. Rules are returned in the order they're evaluated, with the highest-priority rule first.

Endpoint: GET /v1/controls/customDetections/{detectionEventType}
Version: v1
Security: x-api-key

## Security:

  - `x-api-key` (unknown)
    apiKey in header x-api-key

## Path parameters:

  - `detectionEventType` (string, required)
    The custom detection's unique identifier. Always an uppercase identifier beginning with CUSTOM_.

## Response 200:

  - `200` (unknown)
    OK

## Response 200 fields (application/json):

  - `detectionEventType` (string, required)
    The custom detection's unique identifier. Always an uppercase identifier beginning with CUSTOM_.
    Example: CUSTOM_TORRENT_WEBSITE_VISIT

  - `detectionEventName` (string, required)
    The custom detection's name, set when the detection was created. It cannot be updated.
    Example: Torrent website visit

  - `detectionLogic` (string, required)
    The detection logic: one or more detection rules, each a YAML document describing what the browser extension matches on, separated by the standard YAML document separator. It is returned exactly as stored. See the [custom detection specification](/resources/custom-detections/) for the format of the YAML.
    Example: input: web_request
metadata:
  indicator: TORRENT_MAGNET_LINK_DETECTED
conditions:
  request_url:
    scheme: magnet


  - `rules` (array, required)
    The custom detection's control rules, in priority order. The first rule that matches wins.

  - `rules.id` (string)
    The rule's unique identifier.
    Example: c478966c-f927-411c-b919-179832d3d50c

  - `rules.name` (string, required)
    A short name to help you recognise the rule.
    Example: Warn Finance about torrent sites

  - `rules.enabled` (boolean, required)
    Whether the rule is active.
    Example: true

  - `rules.mode` (string, required)
    What happens when the rule matches.
    Enum: "MONITOR", "WARN", "BLOCK", "OFF"

  - `rules.severity` (string)
    The severity of a detection this rule produces. Required for every mode except OFF.
    Enum: "LOW", "MEDIUM", "HIGH", "CRITICAL"

  - `rules.title` (string)
    Heading shown to the user. Required for modes WARN and BLOCK.
    Example: Torrent sites are not allowed

  - `rules.subtext` (string)
    Message shown to the user. Markdown is supported. Required for modes WARN and BLOCK.
    Example: Downloading torrents on company devices is not permitted.

  - `rules.buttonText` (string)
    Label for the message's action button. Required for mode WARN.
    Example: I understand

  - `rules.detectOnInternalHosts` (boolean)
    Whether the rule also applies to private IPs and internal hosts. False when mode is set to OFF.

  - `rules.criteria` (object)
    Restrict the rule to apply only under the specified conditions.

  - `rules.criteria.employeeIds` (object)
    Match specific employees by their employee identifier.
    Example: {"matches":["8c4f1d2e-9a0b-4c1d-8e2f-3a4b5c6d7e8f"]}

  - `rules.criteria.employeeIds.matches` (array, required)
    One or more values to match.

  - `rules.criteria.employeeIds.action` (string)
    Apply the rule to the matched values (INCLUDE) or to everything except them (EXCLUDE). Defaults to INCLUDE when omitted.
    Enum: "INCLUDE", "EXCLUDE"

  - `rules.criteria.employeeGroups` (object)
    Match employees by the groups they belong to.
    Example: {"matches":["Finance","Engineering"]}

## Response 404:

  - `404` (unknown)
    Not Found