# Replace a custom detection

Replaces the custom detection's logic and rules with what you send. Any rule
you don't include is deleted. The detection event name cannot be changed,
and is ignored if you send one.
A rule with an `id` updates the existing rule with that `id`. A rule without
an `id` is created. Rules are evaluated in the order you send them, and the
first rule that matches wins.
To change part of a detection, retrieve it first, apply your changes, and
send the complete detection back. Sending a detection that matches what's
stored, rule `id`s included, changes nothing, so a job that re-syncs your
detections is safe to run repeatedly.

Endpoint: PUT /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_.

## Request body:

  - `application/json` (unknown)
    The custom detection's complete desired state.

## Request fields (application/json):

  - `detectionEventType` (string)
    Optional. The custom detection's unique identifier cannot be updated, so when present this must equal the detection event type in the URL.
    Example: CUSTOM_TORRENT_WEBSITE_VISIT

  - `detectionEventName` (string)
    Optional. The custom detection's name cannot be updated, so this field is ignored: the stored name is kept and returned in the response. It is accepted so that a GET response body can be sent back unchanged.
    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 complete list of control rules the custom detection should have, in priority order. May be empty.

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

## Request examples:

  - `Monitor everyone` (unknown)

  - `Keep the detection logic but remove all rules` (unknown)

## 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 400:

  - `400` (unknown)
    Bad Request

## Response 403:

  - `403` (unknown)
    Forbidden (read-only API key)

## Response 404:

  - `404` (unknown)
    Not Found