Assign Tags

post /public_api/v1/tags/agents/assign

Assign one or more tags to one or more endpoints.

Required license: Cortex XDR Prevent or Cortex XDR Pro per Endpoint

CURL

  curl -X POST \

-H "Accept: application/json" \
 -H "Content-Type: application/json" \
"https://api-yourfqdn/public_api/v1/tags/agents/assign" \
 -d '{
  "request_data" : {
    "filters" : [ {
      "field" : "endpoint_id_list",
      "value" : [ "value", "value" ],
      "operator" : "in"
    }, {
      "field" : "endpoint_id_list",
      "value" : [ "value", "value" ],
      "operator" : "in"
    } ],
    "tag" : "tag"
  }
}'
  

Request

Body

optional

Example: {"request_data":{"filters":[{"field":"endpoint_id_list","operator":"in","value":[""]}],"tag":""}}

request_data

optional

filters

optional

Array

An array of filter fields.

field

required

String (Enum)

String that identifies the field the filter is matching. Filters are based on the following keywords:

endpoint_id_list: List of endpoint IDs.
last_seen: When an endpoint was last seen.
first_seen: When an endpoint was first seen.
dist_name: Distribution / Installation Package name.
ip_list: List of IP addresses.
platform: Platform name.
alias: Alias name.
hostname: Hostname.
isolate: If the endpoint was isolated.
username: Name of user.
scan_status: Status of the scan.
group_name: Group name the agent belongs to.
endpoint_status: Status of the endpoint ID.
operational_status: Operational status.
public_ip_list: List of public IP addresses.

Allowed values:

endpoint_id_list

endpoint_status

dist_name

ip_list

group_name

platform

alias

isolate

hostname

operator

required

String (Enum)

String that identifies the comparison operator you want to use for this filter. Valid keywords and values are: in

endpoint_id_list, dist_name, group_name, alias, hostname, username, operational_status: List of strings.
endpoint_status: Permitted values are connected, lost, disconnected, uninstalled.
ip_list, public_ip_list: List of strings, for example "192.168.5.12".
platform: Permitted values are windows, linux, macos, android, ios.
isolate: Permitted values are isolated or unisolated.
scan_status: Permitted values are none, pending, in_progress, canceled, aborted, pending_cancellation, success, or error.
operational_status: Permitted values are protected, partially_protected, unprotected. gte / lte
first_seen and last_seen: Integer in timestamp epoch milliseconds.

Allowed values:

gte

lte

value

required

Array of strings

Value that this filter must match. The contents of this field will differ depending on the endpoint field that you specified for this filter:

endpoint_id_list, dist_name, group_name, alias, hostname, username, operational_status: List of strings.
endpoint_status: Must contain only the following valid values: connected, disconnected, lost, or uninstalled.
operational_status: Must contain only the following valid values: protected, partially_protected, unprotected.
ip_list, public_ip_list: String list of IP addresses.
platform: Must contain only the following valid values: windows, linux, macos, android, or ios.
isolate: Must contain only the following valid values: isolated or unisolated.
scan_status: Must contain only the following valid values: none, pending, in_progress, canceled, aborted, pending_cancellation, success, or error.
first_seen and last_seen: Integer in timestamp epoch milliseconds.

tag

optional

String

The tag you want to assign.

Responses

Successful response

Body

Bad Request. Got an invalid JSON.

Body

The query result upon error.

err_code

optional

String

HTTP response code.

err_msg

optional

String

Error message.

Example: {"line": 1, "column": 19, "message": "no viable alternative at input '|alter2'"}

err_extra

optional

String

Additional information describing the error.

Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.

Body

The query result upon error.

err_code

optional

String

HTTP response code.

err_msg

optional

String

Error message.

Example: {"line": 1, "column": 19, "message": "no viable alternative at input '|alter2'"}

err_extra

optional

String

Additional information describing the error.

Unauthorized access. User does not have the required license type to run this API.

Body

The query result upon error.

err_code

optional

String

HTTP response code.

err_msg

optional

String

Error message.

Example: {"line": 1, "column": 19, "message": "no viable alternative at input '|alter2'"}

err_extra

optional

String

Additional information describing the error.

Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.

Body

The query result upon error.

err_code

optional

String

HTTP response code.

err_msg

optional

String

Error message.

Example: {"line": 1, "column": 19, "message": "no viable alternative at input '|alter2'"}

err_extra

optional

String

Additional information describing the error.

x Internal server error. A unified status for API communication type errors.

Body

The query result upon error.

err_code

optional

String

HTTP response code.

err_msg

optional

String

Error message.

Example: {"line": 1, "column": 19, "message": "no viable alternative at input '|alter2'"}

err_extra

optional

String

Additional information describing the error.