# Add a custom detection

Creates a custom detection from the name, detection logic and rules you send. The detection event type is derived from the name, returned in the response, and cannot be changed afterwards. Rules are evaluated in the order you send them, and the first rule that matches wins.

Endpoint: POST /v1/controls/customDetections
Version: v1
Security: x-api-key

## Request fields (application/json):

  - `detectionEventName` (string, required)
    The custom detection's name. May only contain letters, numbers, spaces and underscores. The detection event type identifying the detection is derived from it (uppercased, spaces become underscores, prefixed with CUSTOM_) and returned in the response.
    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 stored exactly as sent. 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 control rules the custom detection starts with, in priority order. At least one is required.

  - `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)
    Rule enabled on internal hosts.

  - `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 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)
    Rule enabled on internal hosts.

  - `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"]}