--- title: "Using API Custom Configuration Channels" slug: "using-api-custom-configuration-channels-1" updated: 2026-09-08T19:19:55Z published: 2026-09-08T19:19:55Z canonical: "docs.trellix.com/using-api-custom-configuration-channels-1" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.trellix.com/llms.txt > Use this file to discover all available pages before exploring further. # Using API Custom Configuration Channels [Skip to main content](/docs/using-api-custom-configuration-channels-1#content-wrapper) API custom configuration channels allow you to manually supply agent configuration file settings to multiple hosts included in one or more host sets. Using the API, you can create, modify, and delete custom configuration channels. You can also use the API to review the channel definitions and to obtain a list of the agent settings for a specific host. Configuration file settings applied using an API custom configuration channel replace all existing agent configuration settings. If any configuration file settings are not specified in a custom configuration channel, the *default values* for the Trellix Endpoint Security (HX) xAgent settings are used. See the [Agent Configuration File Reference](/docs/xagent-configuration-file-reference-1) for all default values. The agent default values are not necessarily the same as the Web UI default values for the same configuration options. Any changes you make to these values in the Web UI are ignored by the values applied after you use an API custom configuration channel to change the agent settings. The only exceptions to this are the values for the `credentials` and `serverlist` sections of the configuration file and the following individual configuration settings: `channel`, `id`, `name`, `ts`, `type`, and `version`. The values for these configuration file settings cannot be specified using custom configuration channels and any attempts to do so will be overridden by the Endpoint Security (HX) API with values established during initial Endpoint Security (HX) server and agent deployment. ### Important Trellix recommends that you provide settings for *every* configuration file setting when you create an API custom configuration channel. If you do not provide a value for an agent configuration file setting, the agent default values are used. Prerequisites - **api_admin** authorization for the API - Custom configuration channels can only be specified for hosts running Endpoint Security (HX) xAgent software version 20 or greater. Any hosts running versions earlier than version 20 that are included in the host sets of a custom configuration channel are ignored. - You must have one or more host sets defined in the Web UI that identify the host endpoints to which you want the new configuration settings applied. For information about managing host sets, see the *Endpoint Security (HX) Server User Guide*. In addition, you must know the IDs for the host sets before you create a custom configuration channel that will include them. Host set IDs can be identified using the API. See [Identifying Host Set IDs Using the API](/docs/using-api-custom-configuration-channels-1#UUID-2348da9a-b41c-30ca-2f3b-c32cd25ddd3d) . The following sections describe custom configuration channel behavior and how to create and delete a custom configuration channel request. For information on API custom configuration channel endpoints, see the *Endpoint Security (HX) REST API Guide*. - [Agent Configuration Setting Hierarchy](/docs/using-api-custom-configuration-channels-1#UUID-405fee1e-e738-be0e-8a2f-1fa3419314af) - [Understanding Configuration Channel Priorities](/docs/using-api-custom-configuration-channels-1#UUID-80f86feb-845e-1513-145f-ca38c22b9516) - [Host Sets in Multiple Channels](/docs/modifying-the-configuration-file-for-a-single-endpoint-1) - [Identifying Host Set IDs Using the API](/docs/using-api-custom-configuration-channels-1#UUID-2348da9a-b41c-30ca-2f3b-c32cd25ddd3d) - [Creating a Custom Configuration Channel](/docs/using-api-custom-configuration-channels-1#UUID-41aa9da4-f662-2ec0-4d71-c7a875ed4e4e) - [Listing Custom Configuration Channels](/docs/using-api-custom-configuration-channels-1#UUID-e9d7a5c4-ea05-6ec4-b5e6-4cb869238026) - [Deleting a Custom Configuration Channel](/docs/using-api-custom-configuration-channels-1#UUID-4907c8df-1eda-2f77-13eb-615c0c89082b) - [Obtaining a List of Agent Configuration Settings](/docs/using-api-custom-configuration-channels-1#UUID-d6396454-6dd5-99b9-261c-53bee190b989) ##### xAgent Configuration Setting Hierarchy Agent configuration settings are normally specified for a host using the Web UI. However, if a custom configuration channel is created for a host set, any agent configuration settings established using the Web UI are ignored for the hosts included in that host set. To return to using the Web UI agent settings instead of the custom configuration channel settings for a host, you must first remove the host sets that include that host from any custom configuration channels. As long as a host is included in a host set used by a custom configuration channel, its agent settings are established by the custom configuration channel. When a host is no longer included in a host set used by a custom configuration channel, its agent settings are established by the Web UI settings. In addition, if a host is included in multiple host sets with different custom configuration channels, channel priority numbers are used to determine which agent settings apply to the host. See [Understanding Configuration Channel Priorities](/docs/using-api-custom-configuration-channels-1#UUID-80f86feb-845e-1513-145f-ca38c22b9516). ##### Understanding Configuration Channel Priorities A single host can be included in multiple host sets, which may have different custom configuration channels. To determine which configuration settings should be used for a host included in multiple configuration channels, a priority number is assigned when you create the custom configuration channel. Channels with the lowest priority numbers are given the highest priority. You can list the defined custom configuration channels to see their priorities. See [Listing Custom Configuration Channels](/docs/using-api-custom-configuration-channels-1#UUID-e9d7a5c4-ea05-6ec4-b5e6-4cb869238026). ###### Priority Number Behavior for New Channels Priority numbers for custom configuration channels are set when you create the channels. However, priority numbers cannot be skipped. If you skip a priority number when you create a channel or if you leave the priority blank, the API will automatically assign it the next highest priority number in the channel sequence. For example, the first custom configuration channel you create will be given a priority of 1, regardless of what you specify as its priority. The second custom configuration channel you create will be given a priority number of 2, regardless of what you specify. This is portrayed in the following table. | Channel Creation Order | Name | Requested Priority | Assigned Priority | | --- | --- | --- | --- | | 1 | Channel1 | 6000 | 1 | | 2 | Channel2 | 5 | 2 | If you create a custom configuration channel with the same priority number as an existing channel, the newer channel is given its requested priority number and the priority numbers of the other channels are adjusted upward. This is shown in the following table. | Channel Creation Order | Name | Requested Priority | Assigned Priority | | --- | --- | --- | --- | | 1 | Channel1 | 1 | 2 | | 2 | Channel2 | 2 | 3 | | 3 | Channel3 | 1 | 1 | ###### Priority Number Behavior for Changed Channel Priorities If you change the priority number of a custom configuration channel, the priority numbers of the other channels may or may not be adjusted, depending on how the priority number is modified. - If you change the priority of a custom configuration channel to a lower number (giving it higher priority), all the priority numbers of the configuration channels between the two priority numbers are increased by one. For example, suppose you have five channels with priorities 1 through 5 and you change the channel with priority 4 to priority 2. The following table shows what happens to the channel priority numbers. | Name | Original Priority | Priority After Change | | --- | --- | --- | | Channel1 | 1 | 1 | | Channel2 | 2 | 3 | | Channel3 | 3 | 4 | | Channel4 | 4 | 2 | | Channel5 | 5 | 5 | - If you change the priority of a custom configuration channel to a higher number (giving it lower priority), all the priority numbers of the configuration channels between the two priority numbers are decreased by one. For example, suppose you change the channel with priority 2 to priority 4. The following table shows what happens to the channel priority numbers. | Name | Original Priority | Priority After Change | | --- | --- | --- | | Channel1 | 1 | 1 | | Channel2 | 2 | 4 | | Channel3 | 3 | 2 | | Channel4 | 4 | 3 | | Channel5 | 5 | 5 | ###### Priority Number Behavior for Deleted Channels When you delete a custom configuration channel, the priority numbers are adjusted so that the channels with higher priority numbers are all reduced by one. For example, suppose you delete the channel with priority 3 from a series of channels. The following table shows what happens to the channel priority numbers. | Channel Name | Original Priority | Priority After Delete | | --- | --- | --- | | Channel1 | 1 | 1 | | Channel2 | 2 | 2 | | Channel3 | 3 | deleted | | Channel4 | 4 | 3 | | Channel5 | 5 | 4 | ##### Identifying Host Set IDs Using the API Before you create or update custom configuration channels in the API, you should identify the host set IDs of the host sets you will be using in those channel definitions. **To identify host set IDs using the API:** 1. Use an API to request a list of the host sets defined for the Endpoint Security server. Here is a sample cURL request. The host sets must already be defined in the Web UI. `curl 'https://<HX IP address>:<port number>/hx/api/v3/host_sets' -X 'GET' -H 'X-FeApi-Token: <API token>' -H 'Accept: application/json'` The response body to the request provides the following information about each host set. ```                        "_id": , "name": "", "type": "", "_revision": "yyyymmddnnnnnnnnnnnnnnn", "url": "/" }, ``` For complete information on API custom configuration channel endpoints, see the *Endpoint Security (HX) REST API Guide*. 2. Locate the host sets you want to use in a custom configuration channel in the response body of the API request. Make note of their host set IDs. ##### Creating a custom configuration channel Trellix recommends that you specify *every* configuration file setting (for which you do not want the agent default values) when you create a custom configuration channel. See [Agent Configuration File Reference](/docs/xagent-configuration-file-reference-1). The only exceptions to this are the values for the `credentials` and `serverlist` sections of the configuration file and the following individual configuration settings: `channel`, `id`, `name`, `ts`, `type`, and `version`. The values for these configuration file settings cannot be specified using custom configuration channels and any attempts to do so will be overridden by the Endpoint Security (HX) API with values established during Endpoint Security (HX) server and agent deployment. **To create a custom configuration channel:** - Use the API to request the custom configuration channel be added. Here is a sample cURL request. `curl 'http://<HX_IP_address>:<port_number>/hx/api/v3/host_policies/channels' -X 'POST' --data-binary '{"name”:”<name>","host_sets":[ {"_id":<host_set_ID1>}, {"_id":<host_set_ID2>},...], "description":"<description>","priority":<priority> configuration: {"<key1>":"<value1>", "<key2>":"<value2>",...}' -H 'X-FeApi-Token: <API_token>' -H 'Accept: application/json' -H 'Content-Type: application/json'` To identify host set IDs, see [Identifying Host Set IDs Using the API](/docs/using-api-custom-configuration-channels-1#UUID-2348da9a-b41c-30ca-2f3b-c32cd25ddd3d). For information about priority settings, see [Understanding Configuration Channel Priorities](/docs/using-api-custom-configuration-channels-1#UUID-80f86feb-845e-1513-145f-ca38c22b9516). For information about the configuration settings (the key/value pairs in the cURL request above), see [Agent Configuration File Reference](/docs/xagent-configuration-file-reference-1). For complete information on API custom configuration channel endpoints, see the *Endpoint Security (HX) REST API Guide*. ##### Listing Custom Configuration Channels You can list the defined custom configuration channel using the `GET https://<HX_IP_address>:<port_number>/hx/api/v3/host_policies/channels` API endpoint. Channel priorities and channel IDs are shown in the response to this request. See the *Endpoint Security (HX) REST API Guide* for more information about API endpoints for custom configuration channels. ##### Deleting a Custom Configuration Channel **To delete a custom configuration channel:** - Use the API to request the custom configuration channel be deleted. Here is a sample cURL request. `curl 'http://<HX_IP_address>:<port_number>/hx/api/v3/host_policies/channels/<channel ID>' -X 'DELETE' -H 'X-FeApi-Token: <API_token>' ` The channel ID is shown in the response body to the original creation request and can be obtained using the `GET https://<HX_IP_address>:<port_number>/hx/api/v3/host_policies/channels` API endpoint. For complete information on API custom configuration channel endpoints, see the *Endpoint Security (HX) REST API Guide*. ##### Obtaining a list of xAgent configuration settings At any time, you can obtain a list of the agent configuration settings for a host using the `GET hosts/<:agent_id>/configuration/actual.json` API endpoint. See the *Endpoint Security (HX) REST API Guide* for more information about API endpoints for custom configuration channels. :