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

Body parameters

request_dataObject

filtersArray

An array of filter fields.

fieldString (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"

operatorString (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:"in""gte""lte"

valueArray string integer

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.

tagString

The tag you want to assign.

REQUEST BODY

{
    "request_data": {
        "filters": [
            {
                "field": "endpoint_id_list",
                "operator": "in",
                "value": [
                    "<distribution_id>"
                ]
            }
        ],
        "tag": "<tag_name>"
    }
}

CURL

  curl -X 'POST'

        -H
        'Accept: application/json'
      
        -H
        'Content-Type: application/json'
      
      'https://api-yourfqdn/public_api/v1/tags/agents/assign'
    
      -d
      ''

Responses

Successful response

Body

Bad Request. Got an invalid JSON.

Body

err_codeString

HTTP response code.

err_msgString

Error message.

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

err_extraString

Additional information describing the error.

RESPONSE

{
    "err_code": "err_code_example",
    "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
    "err_extra": "err_extra_example"
}

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

Body

err_codeString

HTTP response code.

err_msgString

Error message.

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

err_extraString

Additional information describing the error.

RESPONSE

{
    "err_code": "err_code_example",
    "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
    "err_extra": "err_extra_example"
}

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

Body

err_codeString

HTTP response code.

err_msgString

Error message.

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

err_extraString

Additional information describing the error.

RESPONSE

{
    "err_code": "err_code_example",
    "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
    "err_extra": "err_extra_example"
}

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

Body

err_codeString

HTTP response code.

err_msgString

Error message.

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

err_extraString

Additional information describing the error.

RESPONSE

{
    "err_code": "err_code_example",
    "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
    "err_extra": "err_extra_example"
}

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

Body

err_codeString

HTTP response code.

err_msgString

Error message.

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

err_extraString

Additional information describing the error.

RESPONSE

{
    "err_code": "err_code_example",
    "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
    "err_extra": "err_extra_example"
}