--- sourceDocument: Yokohama API Reference sourceDocumentLink: https://www.servicenow.com/docs/r/yokohama/api-reference Release : - yokohama ft:locale : - en-US ft:publication_title : - Yokohama API Reference ft:clusterId : - crapiref bundleId : - crapiref workflow : - Creator --- # Agent Client Collector API # Agent Client Collector API {#ariaid-title1} * Release version: Yokohama * * Updated January 30, 2025 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 66 minutes to read The Agent Client Collector API provides endpoints to manage actions on available agents and managing policies. This API requires the Agent Client Collector Framework (sn_agent) store application and is provided within the `sn_agent` namespace. The endpoints in this API require the agent_client_collector_admin role. For more information, refer to [Agent Client Collector](https://www.servicenow.com/docs/access?context=acc-landing-page&version=yokohama&pubname=yokohama-it-operations-management&ft:locale=en-US). Agent management endpoints : * Get extensive information of one or more agents. These endpoints are also accessible to users with the agent_client_collector_user role. * [GET /agents/{agent_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-agent_id "Gets the information of a specified agent.") * [GET /agents/list](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-list "Gets a list of agents with related information.") {#agnt_clnt_cll-api__ul_tsy_mkq_dpb} * Submit a request to grab an agent log and retrieving information about the request progress. * [GET /agents/{agent_id}/log](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-log "Requests the log of a specified agent with alive/up status.") * [GET /agents/log/{request_id}/](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-log-request_id "Checks the status of a grab log request.") {#agnt_clnt_cll-api__ul_rpm_4kq_dpb} * Disable or enable agent data collection. * [GET /agents/{agent_id}/data/off](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-data-off "Disables data collection for a specified agent in the up/alive state.") * [GET /agents/{agent_id}/data/on](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-data-on "Enables data collection for a specified agent in the up/alive state.") {#agnt_clnt_cll-api__ul_z43_gkq_dpb} * Restart an agent with [GET /agents/{agent_id}/restart](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-restart "Restarts a specified agent with alive/up status."). * Run discovery on an agent with [GET /agents/{agent_id}/discovery](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-discovery "Runs a discovery check to locate CIs related to an agent. The specified agent must be in alive/up status."). {#agnt_clnt_cll-api__ul_mlz_ckq_dpb} For information on performing similar tasks in a script include, see [AccAgentsAPI](https://developer.servicenow.com/go_to_api.do?ID=AccAgentsAPIAPIScoped&v=utah). Policy management and workflow : Use policy management APIs to view details, activate/deactivate a policy, update a policy, and publish a policy. : To update a policy: 1. Get a list of policies and details with [GET /agents/policies/list](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-policies-list "Gets a list of policies that are in published or unpublished draft state."). This endpoint requires the agent_client_collector_user role. * To update a policy in the Draft state, use the sys_ids retrieved from the policies list in the update endpoints. * To update a policy in Published or Published\* state, get an editable sandbox copy with [GET /agents/policy/sandbox_from_published/{policy_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-policy-sbox-fr "Gets the sandbox copy of a published policy and provides policy details."). Use the sys_ids from this response to modify properties using an update endpoint. {#agnt_clnt_cll-api__ul_mtj_whk_fpb} 2. Modify policy details using an update endpoint. * [POST /agents/update/policy/{policy_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-POST-update-policy "Updates a sandbox copy of a policy.") * [POST /agents/update/check/{check_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-POST-update-check-id "Updates a selected policy check.") * [POST /agents/update/check_param/{param_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-POST-update-check_param "Updates a selected policy check parameter.") * [POST /agents/update/check_secure_param/{param_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-POST-update-check_secure "Updates a selected policy check secure parameter.") {#agnt_clnt_cll-api__ul_mp4_xjk_fpb} 3. Publish the policy using [GET /agents/policy/publish/{policy_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-policy-publish "Publishes a draft policy."). {#agnt_clnt_cll-api__ol_rmk_chk_fpb} : Once published, the policy becomes Active. This API also includes endpoints for activating or deactivating a published policy: * [GET /agents/policy/activate/{policy_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-policy-act "Activates a published policy.") * [GET /agents/policy/deactivate/{policy_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-policy-deact "Deactivates a published policy.") {#agnt_clnt_cll-api__ul_glm_flk_fpb} ## Agent Client Collector - GET /agents/{agent_id} {#ariaid-title2} Gets the information of a specified agent. ### URL format /api/sn_agent/agents/{agent_id} ### Supported request parameters {#agnt_clnt_cll-GET-agent_id__entry__2} | Name | Description | |-|-| | agent_id | Unique ID of an agent listed in the Agent ID column of the Agent Client Collectors \[sn_agent_cmdb_ci_agent\] table. For a list of agent IDs and other details, run the GET /agents/list endpoint. Data type: String | [Table 1. Path parameters] {#agnt_clnt_cll-GET-agent_id__entry__6} | Name | Description | |-|-| | None | | [Table 2. Query parameters] {#agnt_clnt_cll-GET-agent_id__entry__10} | Name | Description | |-|-| | None | | [Table 3. Request body parameters (JSON)] ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-agent_id__entry__14}{#agnt_clnt_cll-GET-agent_id__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 4. Request headers] {#agnt_clnt_cll-GET-agent_id__entry__18} | Header | Description | |-|-| | None | | [Table 5. Response headers] ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-agent_id__entry__22}{#agnt_clnt_cll-GET-agent_id__entry-200-status-code}{#agnt_clnt_cll-GET-agent_id__agntCC-desc-403-user} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 403 | The user does not have the agent_client_collector_user role. | | 404 | Agent with provided ID not found. | [Table 6. Status codes] ### Response body parameters (JSON) {#agnt_clnt_cll-GET-agent_id__entry__30}{#agnt_clnt_cll-GET-agent_id__accAgents-parm-agent-obj-id-entry}{#agnt_clnt_cll-GET-agent_id__accAgents-parm-agent-obj-dataCollect-entry}{#agnt_clnt_cll-GET-agent_id__accAgents-parm-agent-obj-ip-entry}{#agnt_clnt_cll-GET-agent_id__accAgents-parm-agent-obj-dup-entry}{#agnt_clnt_cll-GET-agent_id__accAgents-parm-agent-obj-restart-entry}{#agnt_clnt_cll-GET-agent_id__accAgents-parm-agent-obj-name-entry}{#agnt_clnt_cll-GET-agent_id__accAgents-parm-agent-obj-numChecks-entry}{#agnt_clnt_cll-GET-agent_id__accAgents-parm-agent-obj-status-entry}{#agnt_clnt_cll-GET-agent_id__accAgents-parm-agent-obj-up-entry}{#agnt_clnt_cll-GET-agent_id__accAgents-parm-agent-obj-version-entry} | Name | Description | |-|-| | \ | Array of JSON objects containing extended agent information. { "agent_id": "String", "data_collection": Number, "ip_address": "String", "is_duplicate": Boolean, "is_restart_enabled": Boolean, "name": "String", "number_of_running_checks": Number, "status": Number, "up_since": "String", "version": "String" } | | agent_id | ID of the agent as submitted. Data type: String | | data_collection | Data collection indicates whether scheduled checks are to be run. These checks are a part of the policies scheduled for this agent to run. Possible values: * 0: On -- Checks run as scheduled. * 1: Off (manual) -- Checks have been disabled manually. * 2: Off (auto) -- Checks have been disabled automatically due to high CPU consumption by the {#agnt_clnt_cll-GET-agent_id__ul_w4n_53p_bpb} Data type: Number | | ip_address | Agent IP address. Data type: String | | is_duplicate | Flag that indicates whether this agent is a duplicate of another. There should be only a single agent on a given host. Possible values: * true: The agent has the same host as an Alive/Up agent with a different agent ID. Turn off or uninstall the duplicate * false: This agent has no duplicates in the Alive/Up state. {#agnt_clnt_cll-GET-agent_id__ul_b34_ffl_bpb} Data type: Boolean | | is_restart_enabled | Flag that indicates whether restart is enabled. Agent restart is not configurable. It depends on the OS and the version of the OS the agent is running on. Possible values: * true: Restart is enabled for this agent. * false: Restart is disabled for this agent. {#agnt_clnt_cll-GET-agent_id__ul_bvp_dfl_bpb} Data type: Boolean | | name | Name of the agent. Data type: String | | number_of_running_checks | The number of checks the agent is scheduled to run. These checks are a part of the policies scheduled for this agent to run. Data type: Number | | status | Status of the agent. Possible values: * 0: Alive/Up -- The agent is active. * 1: Warning -- The agent has not received a keep-alive message in the past few minutes. * 2: Down -- The agent has not received a keep-alive message in a long time. * 3: Restarting -- The agent is restarting. {#agnt_clnt_cll-GET-agent_id__ul_adg_ffp_bpb} Data type: Number | | up_since | UTC time since the agent's status became alive/up. The value is in [GlideDateTime](https://www.servicenow.com/docs/dqzTcKZ1S_uzZa27DO05og#c_GlideDateTimeScoped "The scoped GlideDateTime class provides methods for performing operations on GlideDateTime objects.") format. Data type: String | | version | Version of Agent Client Collector the agent is running. Data type: String | [ ] ### cURL request The following example shows how to get agent details. curl "https://instance.service-now.com/api/sn_agent/agents/" \ --request GET \ --header "Accept:application/json" \ --user 'username':'password' Output: { "name": "WIN-V26KAP7PI2G", "status": 2, "agent_id": "074b14e2eb3ce9d4", "ip_address": "10.196.55.14", "number_of_running_checks": 11, "data_collection": 0, "is_restart_enabled": true, "is_duplicate": false, "up_since": "2021-03-31 12:02:17", "version": "2.3.0" } ## Agent Client Collector - GET /agents/{agent_id}/data/off {#ariaid-title3} Disables data collection for a specified agent in the up/alive state. To determine if an agent's data collection is on or off, run the GET /agents/{agent_id} endpoint. ### URL format {#agnt_clnt_cll-GET-data-off__section_bbq_zyc_z4b} /api/sn_agent/agents/{agent_id}/data/off ### Supported request parameters {#agnt_clnt_cll-GET-data-off__section_cbq_zyc_z4b} {#agnt_clnt_cll-GET-data-off__table_oyt_cd3_dpb__entry__2} | Name | Description | |-|-| | agent_id | Unique ID of an agent listed in the Agent ID column of the Agent Client Collectors \[sn_agent_cmdb_ci_agent\] table. For a list of agent IDs and other details, run the GET /agents/list endpoint. Data type: String | [Table 7. Path parameters] {#agnt_clnt_cll-GET-data-off__table_oyt_cd3_dpb} {#agnt_clnt_cll-GET-data-off__table_ebq_zyc_z4b__entry__2} | Name | Description | |-|-| | None | | [Table 8. Query parameters] {#agnt_clnt_cll-GET-data-off__table_ebq_zyc_z4b} {#agnt_clnt_cll-GET-data-off__table_fbq_zyc_z4b__entry__2} | Name | Description | |-|-| | None | | [Table 9. Request body parameters (JSON)] {#agnt_clnt_cll-GET-data-off__table_fbq_zyc_z4b} ### Headers {#agnt_clnt_cll-GET-data-off__section_gbq_zyc_z4b} The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-data-off__table_hbq_zyc_z4b__entry__2}{#agnt_clnt_cll-GET-data-off__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 10. Request headers] {#agnt_clnt_cll-GET-data-off__table_hbq_zyc_z4b} {#agnt_clnt_cll-GET-data-off__table_ibq_zyc_z4b__entry__2} | Header | Description | |-|-| | None | | [Table 11. Response headers] {#agnt_clnt_cll-GET-data-off__table_ibq_zyc_z4b} ### Status codes {#agnt_clnt_cll-GET-data-off__section_jbq_zyc_z4b} The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-data-off__table_epg_2f3_dpb__entry__2}{#agnt_clnt_cll-GET-data-off__entry-200-status-code}{#agnt_clnt_cll-GET-data-off__agntCC-desc-403-admin} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 403 | The user does not have the agent_client_collector_admin role. | | 404 | Agent not found or isn't in the up/alive state. | [Table 12. Status codes] {#agnt_clnt_cll-GET-data-off__table_epg_2f3_dpb} ### Response body parameters (JSON) {#agnt_clnt_cll-GET-data-off__section_nwl_zyc_z4b} {#agnt_clnt_cll-GET-data-off__table_owl_zyc_z4b__entry__2} | Name | Description | |-|-| | message | Message containing operation success or failure results. Data type: String | [ ] {#agnt_clnt_cll-GET-data-off__table_owl_zyc_z4b} ### cURL request {#agnt_clnt_cll-GET-data-off__example_nbq_zyc_z4b} The following example shows how to turn off agent data collection. curl "https://instance.service-now.com/api/sn_agent/agents//data/off" \ --request GET \ --header "Accept:application/json" \ --user 'username':'password' Output: { "message": "Data Collection Disabled For Agent With ID: " } ## Agent Client Collector - GET /agents/{agent_id}/data/on {#ariaid-title4} Enables data collection for a specified agent in the up/alive state. To determine if an agent's data collection is on or off, run the GET /agents/{agent_id} endpoint. ### URL format {#agnt_clnt_cll-GET-data-on__section_dwl_zyc_z4b} /api/sn_agent/agents/{agent_id}/data/on ### Supported request parameters {#agnt_clnt_cll-GET-data-on__section_ewl_zyc_z4b} {#agnt_clnt_cll-GET-data-on__table_oyt_cd3_dpb__entry__2} | Name | Description | |-|-| | agent_id | Unique ID of an agent listed in the Agent ID column of the Agent Client Collectors \[sn_agent_cmdb_ci_agent\] table. For a list of agent IDs and other details, run the GET /agents/list endpoint. Data type: String | [Table 13. Path parameters] {#agnt_clnt_cll-GET-data-on__table_oyt_cd3_dpb} {#agnt_clnt_cll-GET-data-on__table_gwl_zyc_z4b__entry__2} | Name | Description | |-|-| | None | | [Table 14. Query parameters] {#agnt_clnt_cll-GET-data-on__table_gwl_zyc_z4b} {#agnt_clnt_cll-GET-data-on__table_hwl_zyc_z4b__entry__2} | Name | Description | |-|-| | None | | [Table 15. Request body parameters (JSON)] {#agnt_clnt_cll-GET-data-on__table_hwl_zyc_z4b} ### Headers {#agnt_clnt_cll-GET-data-on__section_iwl_zyc_z4b} The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-data-on__table_jwl_zyc_z4b__entry__2}{#agnt_clnt_cll-GET-data-on__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 16. Request headers] {#agnt_clnt_cll-GET-data-on__table_jwl_zyc_z4b} {#agnt_clnt_cll-GET-data-on__table_kwl_zyc_z4b__entry__2} | Header | Description | |-|-| | None | | [Table 17. Response headers] {#agnt_clnt_cll-GET-data-on__table_kwl_zyc_z4b} ### Status codes {#agnt_clnt_cll-GET-data-on__section_lwl_zyc_z4b} The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-data-on__table_y2n_2f3_dpb__entry__2}{#agnt_clnt_cll-GET-data-on__entry-200-status-code}{#agnt_clnt_cll-GET-data-on__agntCC-desc-403-admin} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 403 | The user does not have the agent_client_collector_admin role. | | 404 | Agent not found or isn't in the up/alive state. | [Table 18. Status codes] {#agnt_clnt_cll-GET-data-on__table_y2n_2f3_dpb} ### Response body parameters (JSON) {#agnt_clnt_cll-GET-data-on__section_nwl_zyc_z4b} {#agnt_clnt_cll-GET-data-on__table_owl_zyc_z4b__entry__2} | Name | Description | |-|-| | message | Message containing operation success or failure results. Data type: String | [ ] {#agnt_clnt_cll-GET-data-on__table_owl_zyc_z4b} ### cURL request {#agnt_clnt_cll-GET-data-on__example_pwl_zyc_z4b} The following example shows how to turn on agent data collection. curl "https://instance.service-now.com/api/sn_agent/agents//data/on" \ --request GET \ --header "Accept:application/json" \ --user 'username':'password' Output: { "message": "Data Collection Enabled For Agent With ID: " } ## Agent Client Collector - GET /agents/{agent_id}/discovery {#ariaid-title5} Runs a discovery check to locate CIs related to an agent. The specified agent must be in alive/up status. ### URL format /api/sn_agent/agents/{agent_id}/discovery ### Supported request parameters {#agnt_clnt_cll-GET-discovery__section_ewl_zyc_z4b} {#agnt_clnt_cll-GET-discovery__table_oyt_cd3_dpb__entry__2} | Name | Description | |-|-| | agent_id | Unique ID of an agent listed in the Agent ID column of the Agent Client Collectors \[sn_agent_cmdb_ci_agent\] table. For a list of agent IDs and other details, run the GET /agents/list endpoint. Data type: String | [Table 19. Path parameters] {#agnt_clnt_cll-GET-discovery__table_oyt_cd3_dpb} {#agnt_clnt_cll-GET-discovery__table_gwl_zyc_z4b__entry__2} | Name | Description | |-|-| | None | | [Table 20. Query parameters] {#agnt_clnt_cll-GET-discovery__table_gwl_zyc_z4b} {#agnt_clnt_cll-GET-discovery__table_hwl_zyc_z4b__entry__2} | Name | Description | |-|-| | None | | [Table 21. Request body parameters (JSON)] {#agnt_clnt_cll-GET-discovery__table_hwl_zyc_z4b} ### Headers {#agnt_clnt_cll-GET-discovery__section_iwl_zyc_z4b} The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-discovery__table_jwl_zyc_z4b__entry__2}{#agnt_clnt_cll-GET-discovery__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 22. Request headers] {#agnt_clnt_cll-GET-discovery__table_jwl_zyc_z4b} {#agnt_clnt_cll-GET-discovery__table_kwl_zyc_z4b__entry__2} | Header | Description | |-|-| | None | | [Table 23. Response headers] {#agnt_clnt_cll-GET-discovery__table_kwl_zyc_z4b} ### Status codes {#agnt_clnt_cll-GET-discovery__section_lwl_zyc_z4b} The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-discovery__table_y2n_2f3_dpb__entry__2}{#agnt_clnt_cll-GET-discovery__entry-200-status-code}{#agnt_clnt_cll-GET-discovery__agntCC-desc-403-admin} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 403 | The user does not have the agent_client_collector_admin role. | | 404 | Agent not found or isn't in the up/alive state. | [Table 24. Status codes] {#agnt_clnt_cll-GET-discovery__table_y2n_2f3_dpb} ### Response body parameters (JSON) {#agnt_clnt_cll-GET-discovery__section_nwl_zyc_z4b} {#agnt_clnt_cll-GET-discovery__table_owl_zyc_z4b__entry__2} | Name | Description | |-|-| | message | Message containing operation success or failure results. Data type: String | [ ] {#agnt_clnt_cll-GET-discovery__table_owl_zyc_z4b} ### cURL request The following example shows how to run discovery on an agent with alive/up status. curl "https://instance.service-now.com/api/sn_agent/agents//discovery" \ --request GET \ --header "Accept:application/json" \ --user 'username':'password' Output: { "message": "Running Discovery For Agent With ID: " } ## Agent Client Collector - GET /agents/check_defs/{check_def_id} {#ariaid-title6} Gets a specified check definition with details. ### URL format /api/sn_agent/agents/check_defs/{check_def_id} ### Supported request parameters {#agnt_clnt_cll-GET-check_defs-id__entry__2} | Name | Description | |-|-| | check_def_id | Sys_id of the check definition listed in the Check Definitions \[sn_agent_check_def\] table. Data type: String | [Table 25. Path parameters] {#agnt_clnt_cll-GET-check_defs-id__entry__6} | Name | Description | |-|-| | None | | [Table 26. Query parameters] {#agnt_clnt_cll-GET-check_defs-id__entry__10} | Name | Description | |-|-| | X-Include-Check-Params | Flag that indicates whether existing check parameter details are returned. Information for each standard and secure check parameter is included in a JSON object. Valid values: * true: Return check parameter details. * false: Do not return check parameter details. {#agnt_clnt_cll-GET-check_defs-id__ul_pv3_gqc_wqb} Data type: Boolean Default: False | [Table 27. Request body parameters (JSON)] ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-check_defs-id__entry__14}{#agnt_clnt_cll-GET-check_defs-id__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 28. Request headers] {#agnt_clnt_cll-GET-check_defs-id__entry__18} | Header | Description | |-|-| | None | | [Table 29. Response headers] ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-check_defs-id__entry__22}{#agnt_clnt_cll-GET-check_defs-id__entry-200-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 404 | Check definition was not found with the sys_id provided. | [Table 30. Status codes] ### Response body parameters (JSON) {#agnt_clnt_cll-GET-check_defs-id__entry__28}{#agnt_clnt_cll-GET-check_defs-id__accCkDf-background-desc-ph}{#agnt_clnt_cll-GET-check_defs-id__accCkDf-chkGrp-desc-ph}{#agnt_clnt_cll-GET-check_defs-id__accCkDf-chkTyp-desc-ph}{#agnt_clnt_cll-GET-check_defs-id__accCkDf-command-desc-ph}{#agnt_clnt_cll-GET-check_defs-id__accCkDf-name-desc-ph}{#agnt_clnt_cll-GET-check_defs-id__accCkDf-p-desc-ph}{#agnt_clnt_cll-GET-check_defs-id__accCkDf-p-active-desc-ph}{#agnt_clnt_cll-GET-check_defs-id__accCkDf-p-default-desc-ph}{#agnt_clnt_cll-GET-check_defs-id__accCkDf-p-mando-desc-ph}{#agnt_clnt_cll-GET-check_defs-id__accCkDf-p-name-desc-ph}{#agnt_clnt_cll-GET-check_defs-id__accCkDf-p-id-desc-ph}{#agnt_clnt_cll-GET-check_defs-id__accCkDf-plugins-desc-ph}{#agnt_clnt_cll-GET-check_defs-id__accCkDf-proxy-desc-ph}{#agnt_clnt_cll-GET-check_defs-id__accCkDf-sp-desc-ph}{#agnt_clnt_cll-GET-check_defs-id__accCkDf-sp-active-desc-ph}{#agnt_clnt_cll-GET-check_defs-id__accCkDf-sp-name-desc-ph}{#agnt_clnt_cll-GET-check_defs-id__accCkDf-sp-order-desc-ph}{#agnt_clnt_cll-GET-check_defs-id__accCkDf-sp-id-desc-ph}{#agnt_clnt_cll-GET-check_defs-id__accCkDf-id-desc-ph}{#agnt_clnt_cll-GET-check_defs-id__accCkDf-timeout-desc-ph} | Properties | Description | |-|-| | check | Details of the specified check definition. { "background": Boolean, "check_group": "String", "check_type": "String", "command": "String", "error": "String", "name": "String", "params": [Array], "plugins": [Array], "proxy_valid": Boolean, "secure_params": [Array], "sys_id": "String", "timeout": Number } | | background | Flag that indicates whether this check definition is a background check. A background check is a check which the agent starts execution of and doesn't wait for it to finish running. Valid values: * true: This check definition is a background check. * false: This check definition is not a background check. {#agnt_clnt_cll-GET-check_defs-id__ul_ypb_5ps_5qb} Data type: Boolean | | check_group | Group specified for this check definition. Data type: String | | check_type | Type of check. Possible values: * Events -- Check results are transformed into an Event Management event. * Metrics -- Values from the check result are transformed to metrics. {#agnt_clnt_cll-GET-check_defs-id__ul_gtr_kfb_wqb} Data type: String | | command | Command that the Agent Client Collector executes. Data type: String | | error | Message if there is an error. Null otherwise. Data type: String | | name | Name of the check. Data type: String | | params | List of parameter definitions associated with the check definition. These results are only included if the withParams parameter is set to true. "params": [ { "active": Boolean, "default_value": "String", "mandatory": Boolean, "name": "String", "sys_id": "String" } ] {#agnt_clnt_cll-GET-check_defs-id__accCkDf-p-code} Data type: Array | | params.active | Flag that indicates whether the check parameter is active. Valid values: * true: The check parameter is active. * false: The check parameter is inactive. {#agnt_clnt_cll-GET-check_defs-id__ul_pnb_jyc_wqb} Data type: Boolean | | params.default_value | Specifies the default value for this check parameter. Data type: String | | params.mandatory | Flag that indicates whether the check parameter is required. Valid values: * true: The check parameter is required. * false: The check parameter is optional. {#agnt_clnt_cll-GET-check_defs-id__ul_wtg_2zc_wqb} Data type: Boolean | | params.name | Name of the check parameter. Data type: String | | params.sys_id | Sys_id of the check parameter listed in the Check Secure Parameter Definitions \[sn_agent_check_param_def\] table. Data type: String | | plugins | List of [Agent Client Collector plugins](https://www.servicenow.com/docs/access?context=acc-assets&version=yokohama&pubname=yokohama-it-operations-management&ft:locale=en-US) associated with this check. Data type: Array | | proxy_valid | Flag that indicates whether the check definition policy is set to work as a proxy. Valid values: * true: This check definition policy is set to work as a proxy. * false: This check definition policy is not set to work as a proxy. {#agnt_clnt_cll-GET-check_defs-id__ul_wbf_qps_5qb} Data type: Boolean | | secure_params | List of assigned to this check. These results are only included if the withParams parameter is set to true. "secure_params": [ { "active": Boolean, "name": "String", "order": Number, "sys_id": "String" } ] {#agnt_clnt_cll-GET-check_defs-id__accCkDf-sp-code} Data type: Array | | secure_params.active | Flag that indicates whether the secure parameter is active. Valid values: * true: The secure parameter is active. * false: The secure parameter is inactive. {#agnt_clnt_cll-GET-check_defs-id__ul_g1b_3vc_wqb} Data type: Boolean | | secure_params.name | Name of the secure parameter. Data type: String | | secure_params.order | Order in which the parameter is sent to the check command/script. Data type: Number | | secure_params.sys_id | Sys_id of the secure parameter listed in the Check Secure Parameter Definitions \[sn_agent_check_secure_param_def\] table. Data type: String | | sys_id | Sys_id of the check definition listed in the Check Definitions \[sn_agent_check_def\] table. Data type: String | | timeout | Timeout in seconds. Data type: Number | [ ] ### cURL request The following example shows how to get information for a specified check definition. curl "https://instance.service-now.com/api/sn_agent/agents/check_defs/94436b237f705300f128134f8dfa91a4" \ --request GET \ --header "Accept:application/json" \ --user 'username':'password' Output: { "name": "app.apache.metrics-apache", "command": "metrics-apache-graphite.rb -p {{.labels.params_port}} --path {{.labels.params_path}} -h {{.labels.params_host}}", "plugins": [ "monitoring-plugin-common" ], "timeout": 60, "proxy_valid": true, "background": false, "check_type": "Metrics", "check_group": "Apache", "sys_id": "94436b237f705300f128134f8dfa91a4", "params": [ { "name": "port", "active": true, "mandatory": true, "default_value": "80", "sys_id": "58436b237f705300f128134f8dfa91a8" }, { "name": "path", "active": true, "mandatory": true, "default_value": "/server-status?auto", "sys_id": "98436b237f705300f128134f8dfa91aa" }, { "name": "scheme", "active": false, "mandatory": false, "default_value": null, "sys_id": "a4e57a96db3bbb4035305c55dc9619f6" }, { "name": "host", "active": true, "mandatory": true, "default_value": "127.0.0.1", "sys_id": "d4436b237f705300f128134f8dfa91a6" }, { "name": "ssl_secure_connection", "active": false, "mandatory": false, "default_value": null, "sys_id": "e3b272c4530100106ffeddeeff7b1275" } ], "secure_params": [ { "name": "cred_user_name", "active": true, "order": 1, "sys_id": "2494cd6e53170010f42cddeeff7b1273" }, { "name": "cred_password", "active": true, "order": 2, "sys_id": "35948d6e53170010f42cddeeff7b127f" } ] } ## Agent Client Collector - GET /agents/check_defs/list {#ariaid-title7} Gets a list of check definitions with details. ### URL format /api/sn_agent/agents/check_defs/list ### Supported request parameters {#agnt_clnt_cll-GET-check_defs-list__entry__2} | Name | Description | |-|-| | None | | [Table 31. Path parameters] {#agnt_clnt_cll-GET-check_defs-list__entry__6} | Name | Description | |-|-| | None | | [Table 32. Query parameters] {#agnt_clnt_cll-GET-check_defs-list__entry__10} | Name | Description | |-|-| | X-Enc-Query | An [encoded query string](https://www.servicenow.com/docs/access?context=c_EncodedQueryStrings&version=yokohama&pubname=yokohama-platform-user-interface&ft:locale=en-US) to filter the check definition result list. Use null for an unfiltered list of check definitions in the system. Data type: String | | X-Include-Check-Params | Flag that indicates whether existing check parameter details are returned. Information for each standard and secure check parameter is included in a JSON object. Valid values: * true: Return check parameter details. * false: Do not return check parameter details. {#agnt_clnt_cll-GET-check_defs-list__ul_pv3_gqc_wqb} Data type: Boolean Default: False | | X-Limit | Limits the number of returned records. Set to null to use the default value. Data type: Number Default: 20,000 | [Table 33. Request body parameters (JSON)] ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-check_defs-list__entry__18}{#agnt_clnt_cll-GET-check_defs-list__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 34. Request headers] {#agnt_clnt_cll-GET-check_defs-list__table_ufx_wwq_wqb__entry__2} | Header | Description | |-|-| | None | | [Table 35. Response headers] {#agnt_clnt_cll-GET-check_defs-list__table_ufx_wwq_wqb} ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-check_defs-list__entry__26}{#agnt_clnt_cll-GET-check_defs-list__entry-200-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | [Table 36. Status codes] ### Response body parameters (JSON) {#agnt_clnt_cll-GET-check_defs-list__entry__30}{#agnt_clnt_cll-GET-check_defs-list__accCkDf-background-desc-ph}{#agnt_clnt_cll-GET-check_defs-list__accCkDf-chkGrp-desc-ph}{#agnt_clnt_cll-GET-check_defs-list__accCkDf-chkTyp-desc-ph}{#agnt_clnt_cll-GET-check_defs-list__accCkDf-command-desc-ph}{#agnt_clnt_cll-GET-check_defs-list__accCkDf-name-desc-ph}{#agnt_clnt_cll-GET-check_defs-list__accCkDf-p-desc-ph}{#agnt_clnt_cll-GET-check_defs-list__accCkDf-p-active-desc-ph}{#agnt_clnt_cll-GET-check_defs-list__accCkDf-p-default-desc-ph}{#agnt_clnt_cll-GET-check_defs-list__accCkDf-p-mando-desc-ph}{#agnt_clnt_cll-GET-check_defs-list__accCkDf-p-name-desc-ph}{#agnt_clnt_cll-GET-check_defs-list__accCkDf-p-id-desc-ph}{#agnt_clnt_cll-GET-check_defs-list__accCkDf-plugins-desc-ph}{#agnt_clnt_cll-GET-check_defs-list__accCkDf-proxy-desc-ph}{#agnt_clnt_cll-GET-check_defs-list__accCkDf-sp-desc-ph}{#agnt_clnt_cll-GET-check_defs-list__accCkDf-sp-active-desc-ph}{#agnt_clnt_cll-GET-check_defs-list__accCkDf-sp-name-desc-ph}{#agnt_clnt_cll-GET-check_defs-list__accCkDf-sp-order-desc-ph}{#agnt_clnt_cll-GET-check_defs-list__accCkDf-sp-id-desc-ph}{#agnt_clnt_cll-GET-check_defs-list__accCkDf-id-desc-ph}{#agnt_clnt_cll-GET-check_defs-list__accCkDf-timeout-desc-ph} | Name | Description | |-|-| | check definitions | List of check definition and details provided as JSON objects. [ { "background": Boolean, "check_group": "String", "check_type": "String", "command": "String", "name": "String", "params": [Array], "plugins": [Array], "proxy_valid": Boolean, "secure_params": [Array], "sys_id": "String", "timeout": Number } ] Data type: Array | | background | Flag that indicates whether this check definition is a background check. A background check is a check which the agent starts execution of and doesn't wait for it to finish running. Valid values: * true: This check definition is a background check. * false: This check definition is not a background check. {#agnt_clnt_cll-GET-check_defs-list__ul_ypb_5ps_5qb} Data type: Boolean | | check_group | Group specified for this check definition. Data type: String | | check_type | Type of check. Possible values: * Events -- Check results are transformed into an Event Management event. * Metrics -- Values from the check result are transformed to metrics. {#agnt_clnt_cll-GET-check_defs-list__ul_gtr_kfb_wqb} Data type: String | | command | Command that the Agent Client Collector executes. Data type: String | | name | Name of the check. Data type: String | | params | List of parameter definitions associated with the check definition. These results are only included if the withParams parameter is set to true. "params": [ { "active": Boolean, "default_value": "String", "mandatory": Boolean, "name": "String", "sys_id": "String" } ] {#agnt_clnt_cll-GET-check_defs-list__accCkDf-p-code} Data type: Array | | params.active | Flag that indicates whether the check parameter is active. Valid values: * true: The check parameter is active. * false: The check parameter is inactive. {#agnt_clnt_cll-GET-check_defs-list__ul_pnb_jyc_wqb} Data type: Boolean | | params.default_value | Specifies the default value for this check parameter. Data type: String | | params.mandatory | Flag that indicates whether the check parameter is required. Valid values: * true: The check parameter is required. * false: The check parameter is optional. {#agnt_clnt_cll-GET-check_defs-list__ul_wtg_2zc_wqb} Data type: Boolean | | params.name | Name of the check parameter. Data type: String | | params.sys_id | Sys_id of the check parameter listed in the Check Secure Parameter Definitions \[sn_agent_check_param_def\] table. Data type: String | | plugins | List of [Agent Client Collector plugins](https://www.servicenow.com/docs/access?context=acc-assets&version=yokohama&pubname=yokohama-it-operations-management&ft:locale=en-US) associated with this check. Data type: Array | | proxy_valid | Flag that indicates whether the check definition policy is set to work as a proxy. Valid values: * true: This check definition policy is set to work as a proxy. * false: This check definition policy is not set to work as a proxy. {#agnt_clnt_cll-GET-check_defs-list__ul_wbf_qps_5qb} Data type: Boolean | | secure_params | List of assigned to this check. These results are only included if the withParams parameter is set to true. "secure_params": [ { "active": Boolean, "name": "String", "order": Number, "sys_id": "String" } ] {#agnt_clnt_cll-GET-check_defs-list__accCkDf-sp-code} Data type: Array | | secure_params.active | Flag that indicates whether the secure parameter is active. Valid values: * true: The secure parameter is active. * false: The secure parameter is inactive. {#agnt_clnt_cll-GET-check_defs-list__ul_g1b_3vc_wqb} Data type: Boolean | | secure_params.name | Name of the secure parameter. Data type: String | | secure_params.order | Order in which the parameter is sent to the check command/script. Data type: Number | | secure_params.sys_id | Sys_id of the secure parameter listed in the Check Secure Parameter Definitions \[sn_agent_check_secure_param_def\] table. Data type: String | | sys_id | Sys_id of the check definition listed in the Check Definitions \[sn_agent_check_def\] table. Data type: String | | timeout | Timeout in seconds. Data type: Number | [ ] ### cURL request The following example shows how to retrieve a list of two check definitions with parameter values. curl "https://instance.service-now.com/api/sn_agent/agents/check_defs/list" \ --request GET \ --header "Accept:application/json" \ --user 'username':'password' Output: { "check_definitions": [ { "name": "checks_api_test", "command": "echo hello", "plugins": [], "timeout": 9, "proxy_valid": true, "background": false, "check_type": "TestCheck", "check_group": "computer", "sys_id": "7f1f9026dba530106f4810284b96194f", "params": [], "secure_params": [ { "name": "check_api_test_check_secure_param2", "active": true, "order": 2, "sys_id": "2d30a066dba530106f4810284b9619c1" }, { "name": "check_api_test_check_secure_param1", "active": true, "order": 100, "sys_id": "4c20a066dba530106f4810284b9619a8" } ] }, { "name": "checks_api_test222", "command": "echo hello1212121", "plugins": [], "timeout": 60, "proxy_valid": true, "background": false, "check_type": "TestCheck", "check_group": "computer", "sys_id": "99e12466dba530106f4810284b961976", "params": [ { "name": "check_api_test_check_param_222", "active": true, "mandatory": false, "default_value": "test_test_test", "sys_id": "44026466dba530106f4810284b9619b2" } ], "secure_params": [] } ] } ## Agent Client Collector - GET /agents/exec/background/stop/{request_id} {#ariaid-title8} Stops a background check. To start a background check, use the POST /agents/check_defs/{check_def_id}/run API. ### URL format /api/sn_agent/agents/exec/background/stop/{request_id} ### Supported request parameters {#agnt_clnt_cll-GET-exec-bkgrd-stop__entry__2} | Name | Description | |-|-| | request_id | The ID of a background check request generated by running the POST /agents/check_defs/{check_def_id}/run API. | [Table 37. Path parameters] {#agnt_clnt_cll-GET-exec-bkgrd-stop__entry__6} | Name | Description | |-|-| | None | | [Table 38. Query parameters] {#agnt_clnt_cll-GET-exec-bkgrd-stop__entry__10} | Name | Description | |-|-| | None | | [Table 39. Request body parameters (JSON)] ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-exec-bkgrd-stop__entry__14}{#agnt_clnt_cll-GET-exec-bkgrd-stop__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 40. Request headers] {#agnt_clnt_cll-GET-exec-bkgrd-stop__entry__18} | Header | Description | |-|-| | None | | [Table 41. Response headers] ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-exec-bkgrd-stop__entry__22}{#agnt_clnt_cll-GET-exec-bkgrd-stop__entry-200-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 404 | The request with the ID provided is not found. | [Table 42. Status codes] ### Response body parameters (JSON) {#agnt_clnt_cll-GET-exec-bkgrd-stop__entry__28} | Name | Description | |-|-| | None | | [ ] ### cURL request The following example shows how to stop a background check. curl "https://instance.service-now.com/api/sn_agent/agents/exec/background/stop/02359174db2a30108a0751f4f3961997" \ --request GET \ --header "Accept:application/json" \ --user 'username':'password' ## Agent Client Collector - GET /agents/exec/run/{request_id} {#ariaid-title9} Gets status of the request with the given ID. ### URL format /api/sn_agent/agents/exec/run/{request_id} ### Supported request parameters {#agnt_clnt_cll-GET-exec-run__table_vmf_44q_wqb__entry__2} | Name | Description | |-|-| | request_id | The ID of a background check request generated by running the POST /agents/check_defs/{check_def_id}/run API. | [Table 43. Path parameters] {#agnt_clnt_cll-GET-exec-run__table_vmf_44q_wqb} {#agnt_clnt_cll-GET-exec-run__entry__6} | Name | Description | |-|-| | None | | [Table 44. Query parameters] {#agnt_clnt_cll-GET-exec-run__entry__10} | Name | Description | |-|-| | None | | [Table 45. Request body parameters (JSON)] ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-exec-run__entry__14}{#agnt_clnt_cll-GET-exec-run__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 46. Request headers] {#agnt_clnt_cll-GET-exec-run__entry__18} | Header | Description | |-|-| | None | | [Table 47. Response headers] ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-exec-run__table_zdx_xmq_wqb__entry__2}{#agnt_clnt_cll-GET-exec-run__entry-200-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 202 | Message with provided ID indicating that the request is in progress. | | 400 | Error in the arguments provided in the request body. | | 404 | The request with the ID provided is not found. | | 408 | Execution timeout for the request with the ID provided. | | 500 | Error checking the status or the request with the ID provided. | [Table 48. Status codes] {#agnt_clnt_cll-GET-exec-run__table_zdx_xmq_wqb} ### Response body parameters (JSON) {#agnt_clnt_cll-GET-exec-run__entry__36} | Name | Description | |-|-| | status | Request status. Possible values: * done -- Check is successful. * failure -- Check has failed. See error message for details. * mid_flow -- Request output is being handled by the MID server. * processing -- Check is in progress. * timeout -- Check processing exceeded time limit set in the runCheckForCis() method. {#agnt_clnt_cll-GET-exec-run__ul_edm_1rr_5qb} Data type: String | | err_msg | Error message if any. Possible values: * No agents found for relevant CIs. * No background check request with given ID. * No request with given ID. * No test result with given ID. * Request timeout. {#agnt_clnt_cll-GET-exec-run__ul_qcf_zcq_5qb} Data type: String | [ ] ### cURL request The following example shows how to get the status of a request. curl "https://instance.service-now.com/api/sn_agent/agents/exec/run/12fed13cdb2a30108a0751f4f3961981" \ --request GET \ --header "Accept:application/json" \ --user 'username':'password' ## Agent Client Collector - GET /agents/exec/test/{test_result_id} {#ariaid-title10} Gets the test check status of the given test result. ### URL format /api/sn_agent/agents/exec/test/{test_result_id} ### Supported request parameters {#agnt_clnt_cll-GET-exec-test-result__entry__2} | Name | Description | |-|-| | test_result_id | A test result ID generated by creating a test check request. | [Table 49. Path parameters] {#agnt_clnt_cll-GET-exec-test-result__entry__6} | Name | Description | |-|-| | None | | [Table 50. Query parameters] {#agnt_clnt_cll-GET-exec-test-result__entry__10} | Name | Description | |-|-| | None | | [Table 51. Request body parameters (JSON)] ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-exec-test-result__entry__14}{#agnt_clnt_cll-GET-exec-test-result__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 52. Request headers] {#agnt_clnt_cll-GET-exec-test-result__entry__18} | Header | Description | |-|-| | None | | [Table 53. Response headers] ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-exec-test-result__entry__22}{#agnt_clnt_cll-GET-exec-test-result__entry-200-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 202 | Message with provided ID indicating that the request is in progress. | | 404 | The request with the ID provided is not found. | | 408 | Execution timeout for the request with the ID provided. | | 500 | Error checking the status of the request with the ID provided. | [Table 54. Status codes] ### Response body parameters (JSON) {#agnt_clnt_cll-GET-exec-test-result__entry__34} | Properties | Description | |-|-| | status | Status of the test results. Possible values: * 0: Pending * 1: In progress * 2: Complete * 3: No test result with given ID {#agnt_clnt_cll-GET-exec-test-result__ul_yyq_4bq_5qb} Data type: String | | output | Output describing the status. Data type: String | [ ] ### cURL request The following example shows how get result status of a completed test check request. curl "https://instance.service-now.com/api/sn_agent/agents/check_instances/99e12466dba530106f4810284b961976/test" \ --request POST \ --header "Accept:application/json" \ --user 'username':'password' ## Agent Client Collector - GET /agents/list {#ariaid-title11} Gets a list of agents with related information. ### URL format /api/sn_agent/agents/list ### Supported request parameters {#agnt_clnt_cll-GET-list__entry__2} | Name | Description | |-|-| | None | | [Table 55. Path parameters] {#agnt_clnt_cll-GET-list__entry__6} | Name | Description | |-|-| | None | | [Table 56. Query parameters] {#agnt_clnt_cll-GET-list__entry__10} | Name | Description | |-|-| | None | | [Table 57. Request body parameters (JSON)] ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-list__entry__14}{#agnt_clnt_cll-GET-list__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | | X-Enc-Query | Encoded query on the Agent Client Collectors \[sn_agent_cmdb_ci_agent\] table in standard Glide format. See [Encoded query strings](https://www.servicenow.com/docs/access?context=c_EncodedQueryStrings&version=yokohama&pubname=yokohama-platform-user-interface&ft:locale=en-US). | | X-Limit | Restricts results to a maximum number of agents. Use null or undefined for both if they are not required.Default/Max: 20,000 Data type: Number | [Table 58. Request headers] {#agnt_clnt_cll-GET-list__entry__22} | Header | Description | |-|-| | None | | [Table 59. Response headers] ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-list__table_vxl_353_dpb__entry__2}{#agnt_clnt_cll-GET-list__entry-200-status-code}{#agnt_clnt_cll-GET-list__agntCC-desc-403-user} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 403 | The user does not have the agent_client_collector_user role. | [Table 60. Status codes] {#agnt_clnt_cll-GET-list__table_vxl_353_dpb} ### Response body parameters (JSON) {#agnt_clnt_cll-GET-list__entry__32}{#agnt_clnt_cll-GET-list__accAgents-parm-agent-obj-id-entry}{#agnt_clnt_cll-GET-list__accAgents-parm-agent-obj-dataCollect-entry}{#agnt_clnt_cll-GET-list__accAgents-parm-agent-obj-ip-entry}{#agnt_clnt_cll-GET-list__accAgents-parm-agent-obj-dup-entry}{#agnt_clnt_cll-GET-list__accAgents-parm-agent-obj-restart-entry}{#agnt_clnt_cll-GET-list__accAgents-parm-agent-obj-name-entry}{#agnt_clnt_cll-GET-list__accAgents-parm-agent-obj-numChecks-entry}{#agnt_clnt_cll-GET-list__accAgents-parm-agent-obj-status-entry}{#agnt_clnt_cll-GET-list__accAgents-parm-agent-obj-up-entry}{#agnt_clnt_cll-GET-list__accAgents-parm-agent-obj-version-entry} | Property | Description | |-|-| | \ | Array of JSON objects containing extended agent information. [ { "agent_id": "String", "data_collection": Number, "ip_address": "String", "is_duplicate": Boolean, "is_restart_enabled": Boolean, "name": "String", "number_of_running_checks": Number, "status": Number, "up_since": "String", "version": "String" } ] | | agent_id | ID of the agent as submitted. Data type: String | | data_collection | Data collection indicates whether scheduled checks are to be run. These checks are a part of the policies scheduled for this agent to run. Possible values: * 0: On -- Checks run as scheduled. * 1: Off (manual) -- Checks have been disabled manually. * 2: Off (auto) -- Checks have been disabled automatically due to high CPU consumption by the {#agnt_clnt_cll-GET-list__ul_w4n_53p_bpb} Data type: Number | | ip_address | Agent IP address. Data type: String | | is_duplicate | Flag that indicates whether this agent is a duplicate of another. There should be only a single agent on a given host. Possible values: * true: The agent has the same host as an Alive/Up agent with a different agent ID. Turn off or uninstall the duplicate * false: This agent has no duplicates in the Alive/Up state. {#agnt_clnt_cll-GET-list__ul_b34_ffl_bpb} Data type: Boolean | | is_restart_enabled | Flag that indicates whether restart is enabled. Agent restart is not configurable. It depends on the OS and the version of the OS the agent is running on. Possible values: * true: Restart is enabled for this agent. * false: Restart is disabled for this agent. {#agnt_clnt_cll-GET-list__ul_bvp_dfl_bpb} Data type: Boolean | | name | Name of the agent. Data type: String | | number_of_running_checks | The number of checks the agent is scheduled to run. These checks are a part of the policies scheduled for this agent to run. Data type: Number | | status | Status of the agent. Possible values: * 0: Alive/Up -- The agent is active. * 1: Warning -- The agent has not received a keep-alive message in the past few minutes. * 2: Down -- The agent has not received a keep-alive message in a long time. * 3: Restarting -- The agent is restarting. {#agnt_clnt_cll-GET-list__ul_adg_ffp_bpb} Data type: Number | | up_since | UTC time since the agent's status became alive/up. The value is in [GlideDateTime](https://www.servicenow.com/docs/dqzTcKZ1S_uzZa27DO05og#c_GlideDateTimeScoped "The scoped GlideDateTime class provides methods for performing operations on GlideDateTime objects.") format. Data type: String | | version | Version of Agent Client Collector the agent is running. Data type: String | [ ] ### cURL request The following example shows how to restrict results by query and number. The query returns all agents that are not in the down state with a maximum of two results. curl "https://instance.service-now.com/api/sn_agent/agents/list" \ --request GET \ --header "Accept:application/json" \ --header "X-Enc-Query: agent_extended_info.status!=2" \ --header "X-Limit: 2" \ --user 'username':'password' Output: { "agents": [ { "name": "007-175", "status": 0, "agent_id": "007-175", "ip_address": "11.222.63.66", "number_of_running_checks": 0, "data_collection": 0, "is_restart_enabled": false, "is_duplicate": false, "up_since": "2021-03-24 14:36:45", "version": "2.4.0" }, { "name": "win2016-dc-64bit", "status": 0, "agent_id": "007-64", "ip_address": "10.222.333.42", "number_of_running_checks": 1, "data_collection": 0, "is_restart_enabled": true, "is_duplicate": false, "up_since": "2021-03-24 11:04:38", "version": "2.4.0" } ] } ### cURL request {#agnt_clnt_cll-GET-list__example_es5_ycj_dpb} The following example shows how to list every agent in the system. This example uses no query and no maximum number of results. curl "https://instance.service-now.com/api/sn_agent/agents/list" \ --request GET \ --header "Accept:application/json" \ --user 'username':'password' ## Agent Client Collector - GET /agents/{agent_id}/log {#ariaid-title12} Requests the log of a specified agent with alive/up status. Note: To retrieve the log and check its progress, pass the request ID returned to the GET /agents/log/{request_id}/ endpoint. ### URL format {#agnt_clnt_cll-GET-log__section_kpf_zyc_z4b} /api/sn_agent/agents/{agent_id}/log ### Supported request parameters {#agnt_clnt_cll-GET-log__section_ewl_zyc_z4b} {#agnt_clnt_cll-GET-log__table_oyt_cd3_dpb__entry__2} | Name | Description | |-|-| | agent_id | Unique ID of an agent listed in the Agent ID column of the Agent Client Collectors \[sn_agent_cmdb_ci_agent\] table. For a list of agent IDs and other details, run the GET /agents/list endpoint. Data type: String | [Table 61. Path parameters] {#agnt_clnt_cll-GET-log__table_oyt_cd3_dpb} {#agnt_clnt_cll-GET-log__table_gwl_zyc_z4b__entry__2} | Name | Description | |-|-| | None | | [Table 62. Query parameters] {#agnt_clnt_cll-GET-log__table_gwl_zyc_z4b} {#agnt_clnt_cll-GET-log__table_hwl_zyc_z4b__entry__2} | Name | Description | |-|-| | None | | [Table 63. Request body parameters (JSON)] {#agnt_clnt_cll-GET-log__table_hwl_zyc_z4b} ### Headers {#agnt_clnt_cll-GET-log__section_iwl_zyc_z4b} The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-log__table_jwl_zyc_z4b__entry__2}{#agnt_clnt_cll-GET-log__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 64. Request headers] {#agnt_clnt_cll-GET-log__table_jwl_zyc_z4b} {#agnt_clnt_cll-GET-log__table_kwl_zyc_z4b__entry__2} | Header | Description | |-|-| | None | | [Table 65. Response headers] {#agnt_clnt_cll-GET-log__table_kwl_zyc_z4b} ### Status codes {#agnt_clnt_cll-GET-log__section_lwl_zyc_z4b} The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-log__table_y2n_2f3_dpb__entry__2}{#agnt_clnt_cll-GET-log__entry-200-status-code}{#agnt_clnt_cll-GET-log__agntCC-desc-403-admin} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 403 | The user does not have the agent_client_collector_admin role. | | 404 | Agent not found or isn't in the up/alive state. | [Table 66. Status codes] {#agnt_clnt_cll-GET-log__table_y2n_2f3_dpb} ### Response body parameters (JSON) {#agnt_clnt_cll-GET-log__section_upf_zyc_z4b} {#agnt_clnt_cll-GET-log__table_vpf_zyc_z4b__entry__2} | Name | Description | |-|-| | request_id | Sys_id of a request in the Agent Client Collector Requests \[sn_agent_request\] table. You can use this ID to retrieve the log and check its progress with the GET /agents/log/{request_id}/ endpoint. Data type: String | [ ] {#agnt_clnt_cll-GET-log__table_vpf_zyc_z4b} ### cURL request The following example shows how to get a log request ID. curl "https://instance.service-now.com/api/sn_agent/agents//log" \ --request GET \ --header "Accept:application/json" \ --user 'username':'password' Output: "request_id": "" ## Agent Client Collector - GET /agents/log/{request_id}/ {#ariaid-title13} Checks the status of a grab log request. Detects changes in the log retrieving request sent with GET /api/sn_agent/agents/{agent_id}/log. ### URL format /api/sn_agent/agents/log/{request_id}/ ### Supported request parameters {#agnt_clnt_cll-GET-log-request_id__entry__2} | Name | Description | |-|-| | request_id | Sys_id of a request in the Agent Client Collector Requests \[sn_agent_request\] table. For the request id, run GET /api/sn_agent/agents/{agent_id}/log. Data type: String | [Table 67. Path parameters] {#agnt_clnt_cll-GET-log-request_id__entry__6} | Name | Description | |-|-| | None | | [Table 68. Query parameters] {#agnt_clnt_cll-GET-log-request_id__entry__10} | Name | Description | |-|-| | None | | [Table 69. Request body parameters (JSON)] ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-log-request_id__entry__14}{#agnt_clnt_cll-GET-log-request_id__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 70. Request headers] {#agnt_clnt_cll-GET-log-request_id__entry__18} | Header | Description | |-|-| | None | | [Table 71. Response headers] ### Status codes {#agnt_clnt_cll-GET-log-request_id__section_lwl_zyc_z4b} The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-log-request_id__table_y2n_2f3_dpb__entry__2}{#agnt_clnt_cll-GET-log-request_id__agntCC-desc-403-admin} | Status code | Description | |-|-| | 200 | Request status is done and the grabbed log is ready. | | 202 | Grab log request with provided ID is still in progress. | | 403 | The user does not have the agent_client_collector_admin role. | | 404 | Grab log request with provided ID not found. | | 408 | Grab log request timed out. | | 500 | Grab log request encountered an error. | [Table 72. Status codes] {#agnt_clnt_cll-GET-log-request_id__table_y2n_2f3_dpb} ### Response body parameters (JSON) {#agnt_clnt_cll-GET-log-request_id__entry__36} | Properties | Description | |-|-| | output | Information describing the status. | [ ] ### cURL request The following example shows how to use a request ID to get the status of a grab log request. curl "https://instance.service-now.com/api/sn_agent/agents/log/" \ --request GET \ --header "Accept:application/json" \ --user 'username':'password' Output: { "output": "SensuSnReadFile OK: {\"component\":\"agent\",\"level\":\"info\",\"msg\":\"Agent Protection: cpu of all checks: 0%\",\"time\":\"2021-04-05T00:21:41-07:00\"},... } ## Agent Client Collector - GET /agents/policies/list {#ariaid-title14} Gets a list of policies that are in published or unpublished draft state. ### URL format /api/sn_agent/agents/policies/list ### Supported request parameters {#agnt_clnt_cll-GET-policies-list__entry__2} | Name | Description | |-|-| | None | | [Table 73. Path parameters] {#agnt_clnt_cll-GET-policies-list__entry__6} | Name | Description | |-|-| | None | | [Table 74. Query parameters] {#agnt_clnt_cll-GET-policies-list__entry__10} | Name | Description | |-|-| | None | | [Table 75. Request body parameters (JSON)] ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-policies-list__table_d1q_x5w_dpb__entry__2}{#agnt_clnt_cll-GET-policies-list__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | | X-Enc-Query | Optional. Encoded query string in the standard platform format. | | X-Include-Check-Params | Optional. Flag that indicates whether to return check instances and their parameters in the results. Valid values: * true: Includes check instances and their parameters in the results. * false: Do not include check instances and their parameters in the results. {#agnt_clnt_cll-GET-policies-list__ul_xmj_pyw_dpb} Default: false Data type: Boolean | | X-Include-Checks-And-Agents | Optional. Flag that indicates whether to include check instances and agents in the results. Valid values: * true: Includes check instances and agents in the results. * false: Do not include checks and agents in the results. {#agnt_clnt_cll-GET-policies-list__ul_asz_gvw_dpb} Default: false Data type: Boolean | [Table 76. Request headers] {#agnt_clnt_cll-GET-policies-list__table_d1q_x5w_dpb} {#agnt_clnt_cll-GET-policies-list__table_abd_scx_dpb__entry__2} | Header | Description | |-|-| | None | | [Table 77. Response headers] {#agnt_clnt_cll-GET-policies-list__table_abd_scx_dpb} ### Status codes {#agnt_clnt_cll-GET-policies-list__section_bbd_scx_dpb} The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-policies-list__table_tmf_2gr_z4b__entry__2}{#agnt_clnt_cll-GET-policies-list__entry-200-status-code}{#agnt_clnt_cll-GET-policies-list__agntCC-desc-403-user} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 403 | The user does not have the agent_client_collector_user role. | [Table 78. Status codes] {#agnt_clnt_cll-GET-policies-list__table_tmf_2gr_z4b} ### Response body parameters (JSON) {#agnt_clnt_cll-GET-policies-list__entry__34}{#agnt_clnt_cll-GET-policies-list__agntCC-ph-rb-checks-sbox} | Property | Description | |-|-| | policies | List of policies retrieved. Includes checks and agent in results if queried using specific request headers. For information on policies, see [default checks and policies](https://www.servicenow.com/docs/access?context=agent-policies-checks&version=yokohama&pubname=yokohama-it-operations-management&ft:locale=en-US). { "policies": [ { "active": Boolean, "agent_ids": "String", "checks": [Array], "cred_alias": "String", "credential_alias": "String", "filter": "String", "interval": "Number", "monitored_ci_group": "String", "monitored_ci_script": "String", "monitored_ci_type_filter": Boolean, "monitored_ci_type_group": Boolean, "monitored_ci_type_script": "String", "name": "String", "params": [Array], "publish_status": "String", "secure_params": [Array], "sys_id": "String", "sys_updated_on": "String", "table": "String" } ] } Data type: Array | | policies.active | Flag that indicates whether the policy is active. Valid values: * true: Policy is active. * false: Policy isn't active. {#agnt_clnt_cll-GET-policies-list__ul_qr2_g3x_dpb} Data type: Boolean | | policies.agent_ids | Unique ID of an agent. These results only display if the X-Include-Checks-And-Agents header parameter is set to true. For extended information of an agent, run the ID in the [GET /agents/{agent_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-agent_id "Gets the information of a specified agent.") endpoint. Data type: String Table: In the Agent ID column of the Agent Client Collectors \[sn_agent_cmdb_ci_agent\] table. | | policies.checks | List of objects defining checks listed in the Check Instances \[sn_agent_check\] table. These results only display if the X-Include-Checks-And-Agents or X-Include-Check-Params header parameter is set to true. Data type: Array of Objects "checks": [ { "active": Boolean, "auto_generate": Boolean, "check_type": "String" "command_prefix": "String", "command": "String", "event_status_change_threshold": Number, "event_status_repair_threshold": Number, "interval": Number, "name": "String", "sys_id": "String", "timeout": "String" } ] {#agnt_clnt_cll-GET-policies-list__agntCC-code-rb-checks-sbox} Table: | | policies.checks.active | Flag that indicates whether the policy check is active. Valid values: * true: Policy check is active. * false: Policy check is inactive. {#agnt_clnt_cll-GET-policies-list__ul_j2p_sdt_2pb} Data type: Boolean | | policies.checks.auto_generate | Flag that indicates whether to automatically generate the command with the command_prefix value. Valid values: * true: Automatically populate the command property with active parameter values. * false: Command isn't automatically generated. {#agnt_clnt_cll-GET-policies-list__ul_myc_x2t_2pb} Data type: Boolean | | policies.checks.check_type | Check type specifying the monitoring option. Possible values: * Discovery: Check that locates CIs related to the agent. * Events: The check's result is transformed into an Event Management event. * Metrics: The values from the check result are transformed to metrics. {#agnt_clnt_cll-GET-policies-list__ul_pgd_42t_2pb} Data type: String | | policies.checks.command | Command that the Agent Client Collector executes. Parameter taken from a template or monitored CI. Note: If auto_generate is true, this property is automatically populated with the prefix and flags of the active parameters listed in the parameters object. Data type: String | | policies.checks.command_prefix | If the auto_generate property is true, this command is used for automatic generation. The prefix consists of any portion of the command which is static (does not change), such as the script name. Data type: String | | policies.checks.event_status_change_threshold | Number of consecutive times that a check's response status must happen before a new event is sent. Returns null if not set. For example, if this value is 3, a check whose response status changes from OK to Error generates a new event with an Error status after the third consecutive occurrence of the status change. Data type: Number | | policies.checks.event_status_repair_threshold | Number of consecutive times that a check's response status must improve to close the previous event. Returns null if not set. For example, if this value is 3, a check whose response status changes from Error to OK closes the previous event and generates a new event with an OK status after the third consecutive occurrence of the status change. Data type: Number | | policies.checks.interval | Amount of time in seconds to wait between check executions. For example, a value of 60 means that the check runs every 60 seconds. Data type: Number | | policies.checks.name | Name of the check. Data type: String | | policies.checks.sys_id | Sys_id of the check. Data type: String Table: Check Instances \[sn_agent_check\] | | policies.checks.timeout | Amount of time, in seconds, after which the check execution stops when no output is returned. For example, a value of 60 means that when the check execution doesn't return a value for 60 seconds, the execution stops. Data type: String | | policies.cred_alias | Credential name. Data type: String Table: Credentials \[discovery_credentials\] | | policies.credential_alias | Sys_id of the credential alias. Data type: String Table: Connection \& Credential Aliases \[sys_alias\] | | policies.filter | Filter restricting the policy's checks to monitor only the specified criteria. Data type: String | | policies.interval | Amount of time in seconds to wait between policy checks. For example, a value of 60 means that the check runs every 60 seconds. Note: The value of the checks.interval property overrides the value configured in this field. Data type: Number | | policies.monitored_ci_group | Name of the [CMDB groups](https://www.servicenow.com/docs/access?context=cmdb-groups&version=yokohama&pubname=yokohama-servicenow-platform&ft:locale=en-US) associated with the policy. This field is only applied if the value of the monitored_ci_type_group property is true. Data type: String Table: CMDB Groups \[cmdb_group\] | | policies.monitored_ci_script | Script for monitoring CIs. This field is only applied if the value of the policies.monitored_ci_type_script property is true. Data type: String | | policies.monitored_ci_type_filter | Flag that indicates whether filtering by CI type is enabled. The CI type is listed in the table property. Valid values: * true: Filtering by checks group is enabled. * false: Filtering by checks group is disabled. {#agnt_clnt_cll-GET-policies-list__ul_tvm_fvt_2pb} Data type: Boolean | | policies.monitored_ci_type_group | Flag that indicates whether monitoring by CMDB group type is enabled. Valid values: * true: CMDB group type is enabled. * false: CMDB group type is disabled. {#agnt_clnt_cll-GET-policies-list__ul_jrc_fvt_2pb} Data type: Boolean | | policies.monitored_ci_type_script | Flag that indicates whether the script for monitoring CIs is enabled. Valid values: * true: Script for monitoring CIs is enabled. * false: Script for monitoring CIs is disabled. {#agnt_clnt_cll-GET-policies-list__ul_bs4_3wt_2pb} Data type: Boolean | | policies.name | Name of the policy. Data type: String | | policies.publish_status | Indicates whether the policy is published. Possible values: * Draft: Policy has not been published and is editable using the update endpoints. * Published: Policy is published. The draft (sandbox copy) and published copy are identical. * Published\*: Policy is published, but the draft copy (sandbox view) has changes not found in the published copy. {#agnt_clnt_cll-GET-policies-list__ul_d3k_qzm_fpb} Data type: String | | policies.sys_id | Sys_id of the policy. Data type: String Table: Policies \[sn_agent_policy\] | | policies.sys_updated_on | Date and time that the policy was last updated. Data type: String | | policies.table | Monitored CI-type field on the policy. This field is only applied if monitored_ci_type_filter is true. Data type: String | | policies.params | List of objects containing information of check parameters. These results only display if the X-Include-Check-Params header parameter is set to true. Data type: Array of Objects "params": [ { "active": Boolean, "flag": "String", "mandatory: Boolean, "name": "String", "sys_id": "String", "value": "String", "value_required": Boolean } ] Table: Check Parameters \[sn_agent_check_param\] | | policies.params.active | Flag that indicates whether the check parameter is active. Valid values: * true: Check parameter is active. * false: Check parameter is inactive. {#agnt_clnt_cll-GET-policies-list__ul_u2x_5fv_2pb} Data type: Boolean | | policies.params.flag | Parameter flag to use during check invocation. Data type: String | | policies.params.mandatory | Flag that indicates whether this check is mandatory. Valid values: * true: This check is mandatory. * false: This check is optional. {#agnt_clnt_cll-GET-policies-list__ul_flq_qkv_2pb} Data type: Boolean | | policies.params.name | Name of the parameter. Data type: String | | policies.params.sys_id | Sys_id of the parameter. Data type: String Table: Check Parameters \[sn_agent_check_param\] | | policies.params.value | Value of the parameter. Data type: String | | policies.params.value_required | Flag that indicates whether the information provided by the value property is required. Valid values: * true: The value property is required. * false: The value property is null or not required. {#agnt_clnt_cll-GET-policies-list__ul_ug3_3jv_2pb} Data type: Boolean | | policies.secure_params | List of objects containing information of check secure parameters. For more information, see [Create a secure parameter for a check](https://www.servicenow.com/docs/access?context=acc-create-secure-params&version=yokohama&pubname=yokohama-it-operations-management&ft:locale=en-US). These results only display if the X-Include-Check-Params header parameter is set to true. Data type: Array of Objects "secure_params": [ { "active": Boolean, "name": "String", "order": Number, "sys_id": "String" } ] Table: Check Secure Parameters \[sn_agent_check_secure_param\] | | policies.secure_params.active | Flag that indicates whether the check secure parameter is active. Valid values: * true: The check secure parameter is active. * false: The check secure parameter is inactive. {#agnt_clnt_cll-GET-policies-list__ul_xwy_vfv_2pb} Data type: Boolean | | policies.secure_params.name | Name of the secure parameter. Data type: String | | policies.secure_params.order | Order in which the parameter is sent to the check command/script. Data type: Number | | policies.secure_params.sys_id | Sys_id of the record. Data type: String Table: Check Secure Parameter \[sn_agent_check_secure_param\] | [Table 79. Object] ### cURL request {#agnt_clnt_cll-GET-policies-list__example_dy2_wbx_dpb} The following example shows how to restrict results by query and number. The query returns all active policies and the ID of the associated agent. curl "https://instance.service-now.com/api/sn_agent/agents/policies/list" \ --request GET \ --header "Accept:application/json" \ --header 'X-Enc-Query: active=true ' \ --header 'X-Include-Checks-And-Agents: true' \ --user 'username' : 'password' Output: { "policies": [ { "name": "Basic Discovery", "sys_id": "68bfd27c536113006dfeddeeff7b12be", "active": "true", "interval": "43200", "sys_updated_on": "2020-07-21 10:14:12", "monitored_ci_type_filter": "true", "filter": "discovery_source=AgentClientCollector^ORlast_discoveredRELATIVELT@dayofweek@ago@14", "table": "cmdb_ci_server", "monitored_ci_type_script": "false", "monitored_ci_script": "/*\n Provide a script to get monitored CI type. ...", "monitored_ci_type_group": "false", "monitored_ci_group": "null// group name as seen in cmdb_group table", "cred_alias": "null// credential name as seen in discovery_credentials table", "credential_alias": "null// credential alias sys id as seen in sys_alias table", "publish_status": "Published", "checks": [ { "name": "check-discovery-basic", "sys_id": "5b10c644c7e10010b9a4362c14c260aa", "active": "true", "command": "check_discover.rb", "command_prefix": "check_discover.rb", "auto_generate": "true", "timeout": "60", "interval": "43200", "event_status_change_threshold": null, "event_status_repair_threshold": null, "check_type": "Discovery" } ], "agent_ids": "b1faba21b066256f,a088b75b1b25b0a0" } ] } ## Agent Client Collector - GET /agents/policy/activate/{policy_id} {#ariaid-title15} Activates a published policy. For a list of published policies, use [GET /agents/policies/list](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-policies-list "Gets a list of policies that are in published or unpublished draft state."). This endpoint only supports sys_ids in which the value of the policy's publish_status property is `Published` or `Published*`. ### URL format /api/sn_agent/agents/policy/activate/{policy_id} ### Supported request parameters {#agnt_clnt_cll-GET-policy-act__section_g4n_tcx_dpb} {#agnt_clnt_cll-GET-policy-act__table_n3g_1fs_2pb__entry__2}{#agnt_clnt_cll-GET-policy-act__agntCC-entry-parm-policyID-pub} | Name | Description | |-|-| | policy_id | Sys_id of the published policy. Data type: String Table: Policies \[sn_agent_policy\] | [Table 80. Path parameters] {#agnt_clnt_cll-GET-policy-act__table_n3g_1fs_2pb} {#agnt_clnt_cll-GET-policy-act__table_i4n_tcx_dpb__entry__2} | Name | Description | |-|-| | None | | [Table 81. Query parameters] {#agnt_clnt_cll-GET-policy-act__table_i4n_tcx_dpb} {#agnt_clnt_cll-GET-policy-act__table_j4n_tcx_dpb__entry__2} | Name | Description | |-|-| | None | | [Table 82. Request body parameters (JSON)] {#agnt_clnt_cll-GET-policy-act__table_j4n_tcx_dpb} ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-policy-act__entry__14}{#agnt_clnt_cll-GET-policy-act__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 83. Request headers] {#agnt_clnt_cll-GET-policy-act__entry__18} | Header | Description | |-|-| | None | | [Table 84. Response headers] ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-policy-act__table_ckp_2gr_z4b__entry__2}{#agnt_clnt_cll-GET-policy-act__entry-200-status-code}{#agnt_clnt_cll-GET-policy-act__agntCC-desc-403-admin}{#agnt_clnt_cll-GET-policy-act__entry-500-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 403 | The user does not have the agent_client_collector_admin role. | | 404 | No record found with the provided sys_id. | | 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. | [Table 85. Status codes] {#agnt_clnt_cll-GET-policy-act__table_ckp_2gr_z4b} ### Response body parameters (JSON) {#agnt_clnt_cll-GET-policy-act__table_h5l_bgs_2pb__entry__2} | Header | Description | |-|-| | message | Message containing operation success or failure results. Data type: String | [ ] {#agnt_clnt_cll-GET-policy-act__table_h5l_bgs_2pb} ### cURL request The following example shows how to activate a policy. curl "https://instance.service-now.com/api/sn_agent/agents/policy/activate/" \ --request GET \ --header "Accept:application/json" \ --user 'username' : 'password' Output: { "message": "Operation was successful" } ## Agent Client Collector - GET /agents/policy/deactivate/{policy_id} {#ariaid-title16} Deactivates a published policy. For a list of published policies, use [GET /agents/policies/list](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-policies-list "Gets a list of policies that are in published or unpublished draft state."). This endpoint only supports sys_ids in which the value of the policy's publish_status property is `Published` or `Published*`. ### URL format {#agnt_clnt_cll-GET-policy-deact__section_f4n_tcx_dpb} /api/sn_agent/agents/policy/activate/{policy_id} ### Supported request parameters {#agnt_clnt_cll-GET-policy-deact__section_g4n_tcx_dpb} {#agnt_clnt_cll-GET-policy-deact__table_f4v_qfs_2pb__entry__2}{#agnt_clnt_cll-GET-policy-deact__agntCC-entry-parm-policyID-pub} | Name | Description | |-|-| | policy_id | Sys_id of the published policy. Data type: String Table: Policies \[sn_agent_policy\] | [Table 86. Path parameters] {#agnt_clnt_cll-GET-policy-deact__table_f4v_qfs_2pb} {#agnt_clnt_cll-GET-policy-deact__table_i4n_tcx_dpb__entry__2} | Name | Description | |-|-| | None | | [Table 87. Query parameters] {#agnt_clnt_cll-GET-policy-deact__table_i4n_tcx_dpb} {#agnt_clnt_cll-GET-policy-deact__table_j4n_tcx_dpb__entry__2} | Name | Description | |-|-| | None | | [Table 88. Request body parameters (JSON)] {#agnt_clnt_cll-GET-policy-deact__table_j4n_tcx_dpb} ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-policy-deact__table_l4n_tcx_dpb__entry__2}{#agnt_clnt_cll-GET-policy-deact__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 89. Request headers] {#agnt_clnt_cll-GET-policy-deact__table_l4n_tcx_dpb} {#agnt_clnt_cll-GET-policy-deact__table_m4n_tcx_dpb__entry__2} | Header | Description | |-|-| | None | | [Table 90. Response headers] {#agnt_clnt_cll-GET-policy-deact__table_m4n_tcx_dpb} ### Status codes {#agnt_clnt_cll-GET-policy-deact__section_n4n_tcx_dpb} The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-policy-deact__table_ckp_2gr_z4b__entry__2}{#agnt_clnt_cll-GET-policy-deact__entry-200-status-code}{#agnt_clnt_cll-GET-policy-deact__agntCC-desc-403-admin}{#agnt_clnt_cll-GET-policy-deact__entry-500-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 403 | The user does not have the agent_client_collector_admin role. | | 404 | No record found with the provided sys_id. | | 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. | [Table 91. Status codes] {#agnt_clnt_cll-GET-policy-deact__table_ckp_2gr_z4b} ### Response body parameters (JSON) {#agnt_clnt_cll-GET-policy-deact__section_znm_1mq_fpb} {#agnt_clnt_cll-GET-policy-deact__table_h5l_bgs_2pb__entry__2} | Header | Description | |-|-| | message | Message containing operation success or failure results. Data type: String | [ ] {#agnt_clnt_cll-GET-policy-deact__table_h5l_bgs_2pb} ### cURL request {#agnt_clnt_cll-GET-policy-deact__example_bgj_chs_2pb} The following example shows how to deactivate a policy. curl "https://instance.service-now.com/api/sn_agent/agents/policy/deactivate/" \ --request GET \ --header "Accept:application/json" \ --user 'username' : 'password' Output: { "message": "Operation was successful" } ## Agent Client Collector - GET /agents/policy/publish/{policy_id} {#ariaid-title17} Publishes a draft policy. Use any of the following endpoints to modify a draft or sandbox copy prior to publishing: * [POST /agents/update/policy/{policy_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-POST-update-policy "Updates a sandbox copy of a policy.") * [POST /agents/update/check/{check_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-POST-update-check-id "Updates a selected policy check.") * [POST /agents/update/check_param/{param_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-POST-update-check_param "Updates a selected policy check parameter.") * [POST /agents/update/check_secure_param/{param_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-POST-update-check_secure "Updates a selected policy check secure parameter.") {#agnt_clnt_cll-GET-policy-publish__ul_p14_jbh_fpb} ### URL format /api/sn_agent/agents/policy/publish/{policy_id} ### Supported request parameters {#agnt_clnt_cll-GET-policy-publish__section_g4n_tcx_dpb} {#agnt_clnt_cll-GET-policy-publish__table_n3g_1fs_2pb__entry__2} | Name | Description | |-|-| | policy_id | Sys_id of a policy in the Policies \[sn_agent_policy\] table that is in Draft state or a sandbox copy. * For a list of policies and details including publish state, use [GET /agents/policies/list](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-policies-list "Gets a list of policies that are in published or unpublished draft state."). * To retrieve sandbox copy of a policy, use [GET /agents/policy/sandbox_from_published/{policy_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-policy-sbox-fr "Gets the sandbox copy of a published policy and provides policy details."). {#agnt_clnt_cll-GET-policy-publish__ul_icv_npn_fpb} Data type: String | [Table 92. Path parameters] {#agnt_clnt_cll-GET-policy-publish__table_n3g_1fs_2pb} {#agnt_clnt_cll-GET-policy-publish__table_i4n_tcx_dpb__entry__2} | Name | Description | |-|-| | None | | [Table 93. Query parameters] {#agnt_clnt_cll-GET-policy-publish__table_i4n_tcx_dpb} {#agnt_clnt_cll-GET-policy-publish__table_j4n_tcx_dpb__entry__2} | Name | Description | |-|-| | None | | [Table 94. Request body parameters (JSON)] {#agnt_clnt_cll-GET-policy-publish__table_j4n_tcx_dpb} ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-policy-publish__entry__14}{#agnt_clnt_cll-GET-policy-publish__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 95. Request headers] {#agnt_clnt_cll-GET-policy-publish__entry__18} | Header | Description | |-|-| | None | | [Table 96. Response headers] ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-policy-publish__table_ckp_2gr_z4b__entry__2}{#agnt_clnt_cll-GET-policy-publish__entry-200-status-code}{#agnt_clnt_cll-GET-policy-publish__agntCC-desc-403-admin}{#agnt_clnt_cll-GET-policy-publish__entry-500-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 403 | The user does not have the agent_client_collector_admin role. | | 404 | No record found with the provided sys_id. | | 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. | [Table 97. Status codes] {#agnt_clnt_cll-GET-policy-publish__table_ckp_2gr_z4b} ### Response body parameters (JSON) {#agnt_clnt_cll-GET-policy-publish__section_m1q_bmq_fpb} {#agnt_clnt_cll-GET-policy-publish__table_h5l_bgs_2pb__entry__2} | Header | Description | |-|-| | message | Message containing operation success or failure results. Data type: String | [ ] {#agnt_clnt_cll-GET-policy-publish__table_h5l_bgs_2pb} ### cURL request The following example shows how to publish a policy. curl "https://instance.service-now.com/api/sn_agent/agents/policy/publish/" \ --request GET \ --header "Accept:application/json" \ --user 'username' : 'password' Output: { "message": "Operation was successful" } ## Agent Client Collector - GET /agents/policy/sandbox_from_published/{policy_id} {#ariaid-title18} Gets the sandbox copy of a published policy and provides policy details. Use the sandbox copy to make updates to a policy and publish. You can use the sys_ids in the response body to work with the following endpoints: * [POST /agents/update/policy/{policy_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-POST-update-policy "Updates a sandbox copy of a policy.") * [POST /agents/update/check/{check_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-POST-update-check-id "Updates a selected policy check.") * [POST /agents/update/check_param/{param_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-POST-update-check_param "Updates a selected policy check parameter.") * [POST /agents/update/check_secure_param/{param_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-POST-update-check_secure "Updates a selected policy check secure parameter.") {#agnt_clnt_cll-GET-policy-sbox-fr__ul_p14_jbh_fpb} For a list of published policies, use [GET /agents/policies/list](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-policies-list "Gets a list of policies that are in published or unpublished draft state."). This endpoint only supports sys_ids in which the value of the policy's publish_status property is `Published` or `Published*`. ### URL format /api/sn_agent/agents/policy/sandbox_from_published/{policy_id} ### Supported request parameters {#agnt_clnt_cll-GET-policy-sbox-fr__section_g4n_tcx_dpb} {#agnt_clnt_cll-GET-policy-sbox-fr__table_n3g_1fs_2pb__entry__2}{#agnt_clnt_cll-GET-policy-sbox-fr__agntCC-entry-parm-policyID-pub} | Name | Description | |-|-| | policy_id | Sys_id of the published policy. Data type: String Table: Policies \[sn_agent_policy\] | [Table 98. Path parameters] {#agnt_clnt_cll-GET-policy-sbox-fr__table_n3g_1fs_2pb} {#agnt_clnt_cll-GET-policy-sbox-fr__table_i4n_tcx_dpb__entry__2} | Name | Description | |-|-| | None | | [Table 99. Query parameters] {#agnt_clnt_cll-GET-policy-sbox-fr__table_i4n_tcx_dpb} {#agnt_clnt_cll-GET-policy-sbox-fr__table_j4n_tcx_dpb__entry__2} | Name | Description | |-|-| | None | | [Table 100. Request body parameters (JSON)] {#agnt_clnt_cll-GET-policy-sbox-fr__table_j4n_tcx_dpb} ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-policy-sbox-fr__entry__14}{#agnt_clnt_cll-GET-policy-sbox-fr__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 101. Request headers] {#agnt_clnt_cll-GET-policy-sbox-fr__entry__18} | Header | Description | |-|-| | None | | [Table 102. Response headers] ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-policy-sbox-fr__table_ckp_2gr_z4b__entry__2}{#agnt_clnt_cll-GET-policy-sbox-fr__entry-200-status-code}{#agnt_clnt_cll-GET-policy-sbox-fr__agntCC-desc-403-admin}{#agnt_clnt_cll-GET-policy-sbox-fr__entry-500-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 403 | The user does not have the agent_client_collector_admin role. | | 404 | No record found with the provided sys_id. | | 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. | [Table 103. Status codes] {#agnt_clnt_cll-GET-policy-sbox-fr__table_ckp_2gr_z4b} ### Response body parameters (JSON) {#agnt_clnt_cll-GET-policy-sbox-fr__entry__32} | Property | Description | |-|-| | \ | Extended details of the sandbox copy associated with the policy. For information on policies, see [default checks and policies](https://www.servicenow.com/docs/access?context=agent-policies-checks&version=yokohama&pubname=yokohama-it-operations-management&ft:locale=en-US). { "active": Boolean" "agent_ids": "String", "checks": [Array], "cred_alias": "String", "credential_alias": "String", "filter": "String", "interval": "Number", "monitored_ci_group": "String", "monitored_ci_script": "String", "monitored_ci_type_filter": Boolean, "monitored_ci_type_group": Boolean, "monitored_ci_type_script": "String", "name": "String", "params": [Array], "publish_status": "String", "secure_params": [Array], "sys_id": "String", "sys_updated_on": "String", "table": "String" } | | active | Flag that indicates whether the policy is active. Valid values: * true: Policy is active. * false: Policy isn't active. {#agnt_clnt_cll-GET-policy-sbox-fr__ul_qr2_g3x_dpb} Data type: Boolean | | agent_ids | Unique ID of an agent. These results only display if the X-Include-Checks-And-Agents header parameter is set to true. For extended information of an agent, run the ID in the [GET /agents/{agent_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-agent_id "Gets the information of a specified agent.") endpoint. Data type: String Table: In the Agent ID column of the Agent Client Collectors \[sn_agent_cmdb_ci_agent\] table. | | checks | List of objects defining checks listed in the Check Instances \[sn_agent_check\] table. "checks": [ { "active": Boolean, "auto_generate": Boolean, "check_type": "String" "command_prefix": "String", "command": "String", "event_status_change_threshold": Number, "event_status_repair_threshold": Number, "interval": Number, "name": "String", "sys_id": "String", "timeout": "String" } ] Data type: Array | | checks.active | Flag that indicates whether the policy check is active. Valid values: * true: Policy check is active. * false: Policy check is inactive. {#agnt_clnt_cll-GET-policy-sbox-fr__ul_j2p_sdt_2pb} Data type: Boolean | | checks.auto_generate | Flag that indicates whether to automatically generate the command with the command_prefix value. Valid values: * true: Automatically populate the command property with active parameter values. * false: Command isn't automatically generated. {#agnt_clnt_cll-GET-policy-sbox-fr__ul_myc_x2t_2pb} Data type: Boolean | | checks.check_type | Check type specifying the monitoring option. Possible values: * Discovery: Check that locates CIs related to the agent. * Events: The check's result is transformed into an Event Management event. * Metrics: The values from the check result are transformed to metrics. {#agnt_clnt_cll-GET-policy-sbox-fr__ul_pgd_42t_2pb} Data type: String | | checks.command | Command that the Agent Client Collector executes. Parameter taken from a template or monitored CI. Note: If auto_generate is true, this property is automatically populated with the prefix and flags of the active parameters listed in the parameters object. Data type: String | | checks.command_prefix | If the auto_generate property is true, this command is used for automatic generation. The prefix consists of any portion of the command which is static (does not change), such as the script name. Data type: String | | checks.event_status_change_threshold | Number of consecutive times that a check's response status must happen before a new event is sent. Returns null if not set. For example, if this value is 3, a check whose response status changes from OK to Error generates a new event with an Error status after the third consecutive occurrence of the status change. Data type: Number | | checks.event_status_repair_threshold | Number of consecutive times that a check's response status must improve to close the previous event. Returns null if not set. For example, if this value is 3, a check whose response status changes from Error to OK closes the previous event and generates a new event with an OK status after the third consecutive occurrence of the status change. Data type: Number | | checks.interval | Amount of time in seconds to wait between check executions. For example, a value of 60 means that the check runs every 60 seconds. Data type: Number | | checks.name | Name of the check. Data type: String | | checks.sys_id | Sys_id of the check. The [POST /agents/update/check/{check_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-POST-update-check-id "Updates a selected policy check.") endpoint takes this value to update the sandbox copy. Data type: String Table: Check Instances \[sn_agent_check\] | | checks.timeout | Amount of time, in seconds, after which the check execution stops when no output is returned. For example, a value of 60 means that when the check execution doesn't return a value for 60 seconds, the execution stops. Data type: String | | cred_alias | Credential name. Data type: String Table: Credentials \[discovery_credentials\] | | credential_alias | Sys_id of the credential alias. Data type: String Table: Connection \& Credential Aliases \[sys_alias\] | | filter | Filter restricting the policy's checks to monitor only the specified criteria. Data type: String | | interval | Amount of time in seconds to wait between policy checks. For example, a value of 60 means that the check runs every 60 seconds. Note: The value of the checks.interval property overrides the value configured in this field. Data type: Number | | monitored_ci_group | Name of the [CMDB groups](https://www.servicenow.com/docs/access?context=cmdb-groups&version=yokohama&pubname=yokohama-servicenow-platform&ft:locale=en-US) associated with the policy. This field is only applied if the value of the monitored_ci_type_group property is true. Data type: String Table: CMDB Groups \[cmdb_group\] | | monitored_ci_script | Script for monitoring CIs. This field is only applied if the value of the policies.monitored_ci_type_script property is true. Data type: String | | monitored_ci_type_filter | Flag that indicates whether filtering by CI type is enabled. The CI type is listed in the table property. Valid values: * true: Filtering by checks group is enabled. * false: Filtering by checks group is disabled. {#agnt_clnt_cll-GET-policy-sbox-fr__ul_tvm_fvt_2pb} Data type: Boolean | | monitored_ci_type_group | Flag that indicates whether monitoring by CMDB group type is enabled. Valid values: * true: CMDB group type is enabled. * false: CMDB group type is disabled. {#agnt_clnt_cll-GET-policy-sbox-fr__ul_jrc_fvt_2pb} Data type: Boolean | | monitored_ci_type_script | Flag that indicates whether the script for monitoring CIs is enabled. Valid values: * true: Script for monitoring CIs is enabled. * false: Script for monitoring CIs is disabled. {#agnt_clnt_cll-GET-policy-sbox-fr__ul_bs4_3wt_2pb} Data type: Boolean | | name | Name of the policy. Data type: String | | publish_status | Indicates whether the policy is published. Possible values: * Draft: Policy has not been published and is editable using the update endpoints. * Published: Policy is published. The draft (sandbox copy) and published copy are identical. * Published\*: Policy is published, but the draft copy (sandbox view) has changes not found in the published copy. {#agnt_clnt_cll-GET-policy-sbox-fr__ul_d3k_qzm_fpb} Data type: String | | params | List of objects containing information of check parameters. These results only display if the X-Include-Check-Params header parameter is set to true. Data type: Array of Objects "params": [ { "active": Boolean, "flag": "String", "mandatory: Boolean, "name": "String", "sys_id": "String", "value": "String", "value_required": Boolean } ] Table: Check Parameters \[sn_agent_check_param\] | | params.active | Flag that indicates whether the check parameter is active. Valid values: * true: Check parameter is active. * false: Check parameter is inactive. {#agnt_clnt_cll-GET-policy-sbox-fr__ul_u2x_5fv_2pb} Data type: Boolean | | params.flag | Parameter flag to use during check invocation. Data type: String | | params.mandatory | Flag that indicates whether this check is mandatory. Valid values: * true: This check is mandatory. * false: This check is optional. {#agnt_clnt_cll-GET-policy-sbox-fr__ul_flq_qkv_2pb} Data type: Boolean | | params.name | Name of the parameter. Data type: String | | params.sys_id | Sys_id of the parameter listed in the Check Parameters \[sn_agent_check_param\] table. The [POST /agents/update/check_param/{param_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-POST-update-check_param "Updates a selected policy check parameter.") endpoint takes this value to update the sandbox copy. Data type: String | | params.value | Value of the parameter. Data type: String | | params.value_required | Flag that indicates whether the information provided by the value property is required. Valid values: * true: The value property is required. * false: The value property is null or not required. {#agnt_clnt_cll-GET-policy-sbox-fr__ul_ug3_3jv_2pb} Data type: Boolean | | secure_params | List of objects containing information of check secure parameters. For more information, see [Create a secure parameter for a check](https://www.servicenow.com/docs/access?context=acc-create-secure-params&version=yokohama&pubname=yokohama-it-operations-management&ft:locale=en-US). These results only display if the X-Include-Check-Params header parameter is set to true. Data type: Array of Objects "secure_params": [ { "active": Boolean, "name": "String", "order": Number, "sys_id": "String" } ] Table: Check Secure Parameters \[sn_agent_check_secure_param\] | | secure_params.active | Flag that indicates whether the check secure parameter is active. Valid values: * true: The check secure parameter is active. * false: The check secure parameter is inactive. {#agnt_clnt_cll-GET-policy-sbox-fr__ul_xwy_vfv_2pb} Data type: Boolean | | secure_params.name | Name of the secure parameter. Data type: String | | secure_params.order | Order in which the parameter is sent to the check command/script. Data type: Number | | secure_params.sys_id | Sys_id of the record. The [POST /agents/update/check_secure_param/{param_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-POST-update-check_secure "Updates a selected policy check secure parameter.") endpoint takes this value to update the sandbox copy. Data type: String Table: Check Secure Parameter \[sn_agent_check_secure_param\] | | sys_id | Sys_id of the policy. The [POST /agents/update/policy/{policy_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-POST-update-policy "Updates a sandbox copy of a policy.") endpoint takes this value to update the sandbox copy. Data type: String Table: Policies \[sn_agent_policy\] | | sys_updated_on | Date and time that the policy was last updated. Data type: String | | table | Monitored CI-type field on the policy. This field is only applied if monitored_ci_type_filter is true. Data type: String | [ ] ### cURL request The following shows how to get information of the Docker Container Metrics policy. curl "https://instance.service-now.com/api/sn_agent/agents/policy/sandbox_from_published/" \ --request GET \ --header "Accept:application/json" \ --user 'username':'password' Output: { "name": "Docker Container Metrics", "sys_id": "b01e609a1b9fe4943e7f0b05464bcb91", "active": "false", "interval": "60", "sys_updated_on": "2021-04-05 19:52:28", "monitored_ci_type_filter": "true", "filter": "operational_status=1", "table": "cmdb_ci_docker_container", "monitored_ci_type_script": "false", "monitored_ci_script": "/*\n Provide a script to get monitored CI type.", "monitored_ci_type_group": "false", "monitored_ci_group": "null// group name as seen in cmdb_group table", "cred_alias": "null// credential name as seen in discovery_credentials table", "credential_alias": "null// credential alias sys id as seen in sys_alias table", "publish_status": "Published", "checks": [ { "name": "container.docker.metrics-docker", "sys_id": "701e609a1b9fe4943e7f0b05464bcb94", "active": "true", "command": "metrics-docker-stats.rb -N {{.labels.params_ci_container_id}} -P -n -i", "command_prefix": "metrics-docker-stats.rb -N {{.labels.params_ci_container_id}}", "auto_generate": "true", "timeout": "60", "interval": "60", "event_status_change_threshold": null, "event_status_repair_threshold": null, "check_type": "Metrics", "params": [ { "name": "scheme", "sys_id": "c11e609a1b9fe4943e7f0b05464bcb97", "value": null, "active": "false", "mandatory": "false", "value_required": "true", "flag": "-s" }, ... { "name": "docker_host", "sys_id": "cd1e609a1b9fe4943e7f0b05464bcb97", "value": null, "active": "false", "mandatory": "false", "value_required": "true", "flag": "-H" } ], "secure_params": [] } ] } ## Agent Client Collector - GET /agents/{agent_id}/restart {#ariaid-title19} Restarts a specified agent with alive/up status. If Agent Client Collector performance issues occur, you can restart the agent. Manual restart is supported in the following environments: * Linux-based agents using `systemd` * Windows agents {#agnt_clnt_cll-GET-restart__ul_zzv_z4q_dpb} ### URL format {#agnt_clnt_cll-GET-restart__section_nf5_zyc_z4b} /api/sn_agent/agents/{agent_id}/restart ### Supported request parameters {#agnt_clnt_cll-GET-restart__section_ewl_zyc_z4b} {#agnt_clnt_cll-GET-restart__table_oyt_cd3_dpb__entry__2} | Name | Description | |-|-| | agent_id | Unique ID of an agent listed in the Agent ID column of the Agent Client Collectors \[sn_agent_cmdb_ci_agent\] table. For a list of agent IDs and other details, run the GET /agents/list endpoint. Data type: String | [Table 104. Path parameters] {#agnt_clnt_cll-GET-restart__table_oyt_cd3_dpb} {#agnt_clnt_cll-GET-restart__table_gwl_zyc_z4b__entry__2} | Name | Description | |-|-| | None | | [Table 105. Query parameters] {#agnt_clnt_cll-GET-restart__table_gwl_zyc_z4b} {#agnt_clnt_cll-GET-restart__table_hwl_zyc_z4b__entry__2} | Name | Description | |-|-| | None | | [Table 106. Request body parameters (JSON)] {#agnt_clnt_cll-GET-restart__table_hwl_zyc_z4b} ### Headers {#agnt_clnt_cll-GET-restart__section_iwl_zyc_z4b} The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-restart__table_jwl_zyc_z4b__entry__2}{#agnt_clnt_cll-GET-restart__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 107. Request headers] {#agnt_clnt_cll-GET-restart__table_jwl_zyc_z4b} {#agnt_clnt_cll-GET-restart__table_kwl_zyc_z4b__entry__2} | Header | Description | |-|-| | None | | [Table 108. Response headers] {#agnt_clnt_cll-GET-restart__table_kwl_zyc_z4b} ### Status codes {#agnt_clnt_cll-GET-restart__section_lwl_zyc_z4b} The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-GET-restart__table_y2n_2f3_dpb__entry__2}{#agnt_clnt_cll-GET-restart__entry-200-status-code}{#agnt_clnt_cll-GET-restart__agntCC-desc-403-admin} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 403 | The user does not have the agent_client_collector_admin role. | | 404 | No record found with the provided sys_id or this agent does not support restart. | [Table 109. Status codes] {#agnt_clnt_cll-GET-restart__table_y2n_2f3_dpb} ### Response body parameters (JSON) {#agnt_clnt_cll-GET-restart__section_nwl_zyc_z4b} {#agnt_clnt_cll-GET-restart__table_owl_zyc_z4b__entry__2} | Name | Description | |-|-| | message | Message containing operation success or failure results. Data type: String | [ ] {#agnt_clnt_cll-GET-restart__table_owl_zyc_z4b} ### cURL request {#agnt_clnt_cll-GET-restart__example_zf5_zyc_z4b} The following example shows how to restart an agent. curl "https://instance.service-now.com/api/sn_agent/agents//restart" \ --request GET \ --header "Accept:application/json" \ --user 'username':'password' Output: { "message": "Restarting Agent With ID: " } ## Agent Client Collector - POST /agents/check_defs/{check_def_id}/run {#ariaid-title20} Runs a check against the given configuration item. To stop a background check, use the request ID provided in the GET /agents/exec/background/stop/{request_id} API. ### URL format /api/sn_agent/agents/check_defs/{check_def_id}/run ### Supported request parameters {#agnt_clnt_cll-POST-check-def-run__entry__2} | Name | Description | |-|-| | check_def_id | Sys_id of a check definition in the Check Definitions \[sn_agent_check_def\] table. | [Table 110. Path parameters] {#agnt_clnt_cll-POST-check-def-run__entry__6} | Name | Description | |-|-| | None | | [Table 111. Query parameters] {#agnt_clnt_cll-POST-check-def-run__table_cvh_5gq_wqb__entry__2} | Name | Description | |-|-| | params | Map of parameter names and values. These settings can be used to override the parameter records of the check definition and its specified values. "params": { "": "String" } Data type: Object | | priority | Priority of the request to be set on the ECC queue. Possible values: * 0: interactive * 1: expedited * 2: standard {#agnt_clnt_cll-POST-check-def-run__ul_bkf_hnq_wqb} Data type: Number | | query | Encoded query for retrieving the GlideRecord from the table specified in the table property. Data type: String | | table | Name of the cmdb_ci table for this background check. Data type: String | | timeout | Value of the timeout for the request in seconds. Data type: Number | [Table 112. Request body parameters (JSON)] {#agnt_clnt_cll-POST-check-def-run__table_cvh_5gq_wqb} ### Headers {#agnt_clnt_cll-POST-check-def-run__section_dvh_5gq_wqb} The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-POST-check-def-run__table_evh_5gq_wqb__entry__2}{#agnt_clnt_cll-POST-check-def-run__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 113. Request headers] {#agnt_clnt_cll-POST-check-def-run__table_evh_5gq_wqb} {#agnt_clnt_cll-POST-check-def-run__table_fvh_5gq_wqb__entry__2} | Header | Description | |-|-| | None | | [Table 114. Response headers] {#agnt_clnt_cll-POST-check-def-run__table_fvh_5gq_wqb} ### Status codes {#agnt_clnt_cll-POST-check-def-run__section_gvh_5gq_wqb} The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-POST-check-def-run__table_hvh_5gq_wqb__entry__2}{#agnt_clnt_cll-POST-check-def-run__entry-200-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 400 | The is an error in the arguments provided in the request body. | | 404 | The check definition with the ID provided is not found. | | 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. | [Table 115. Status codes] {#agnt_clnt_cll-POST-check-def-run__table_hvh_5gq_wqb} ### Response body parameters (JSON) {#agnt_clnt_cll-POST-check-def-run__section_ivh_5gq_wqb} {#agnt_clnt_cll-POST-check-def-run__table_jvh_5gq_wqb__entry__2} | Name | Description | |-|-| | requestId | Sys_id of the generated background check request. | [ ] {#agnt_clnt_cll-POST-check-def-run__table_jvh_5gq_wqb} ### cURL request {#agnt_clnt_cll-POST-check-def-run__example_kvh_5gq_wqb} The following example shows how to run a background check and get its request ID. curl "https://instance.service-now.com/api/sn_agent/agents/check_defs/a90d3c361be1301060d2773ad54bcb6f/run" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data "{\"table\":\"sn_agent_check_def\"}" \ --user 'username':'password' Output: { "request_id": "278c0170db2a30108a0751f4f3961926" } ## Agent Client Collector - POST /agents/check_defs/{check_def_id}/test {#ariaid-title21} Enables building test check requests on check definitions. Use this API for the following tasks: * Set the check definition to test * Set the configuration item to run the test against {#agnt_clnt_cll-POST-check-def-test__ul_tdb_gpk_5qb}You can also specify one of the following identifiers to use during the test: * Credential sys_id * Credential alias id * Credential name {#agnt_clnt_cll-POST-check-def-test__ul_tft_qwk_5qb} ### URL format /api/sn_agent/agents/check_defs/{check_def_id}/test ### Supported request parameters {#agnt_clnt_cll-POST-check-def-test__entry__2} | Name | Description | |-|-| | check_def_id | Sys_id of the check definition listed in the Check Definitions \[sn_agent_check_def\] table. | [Table 116. Path parameters] {#agnt_clnt_cll-POST-check-def-test__entry__6} | Name | Description | |-|-| | None | | [Table 117. Query parameters] {#agnt_clnt_cll-POST-check-def-test__entry__10} | Name | Description | |-|-| | ci_id | Sys_id of a CMDB Configuration Item. | | credentials_id | Sys_id of a credentials record. | | credentials_name | Name of the credentials record. | | credentials_alias_id | Sys_id of a credentials alias record. | | credentials_alias_name | Name of a credentials alias. | [Table 118. Request body parameters (JSON)] ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-POST-check-def-test__entry__22}{#agnt_clnt_cll-POST-check-def-test__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 119. Request headers] {#agnt_clnt_cll-POST-check-def-test__entry__26} | Header | Description | |-|-| | None | | [Table 120. Response headers] ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-POST-check-def-test__entry__30}{#agnt_clnt_cll-POST-check-def-test__entry-200-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 500 | Error building the test request. | [Table 121. Status codes] ### Response body parameters (JSON) {#agnt_clnt_cll-POST-check-def-test__section_d5l_yrv_wqb} {#agnt_clnt_cll-POST-check-def-test__table_e5l_yrv_wqb__entry__2} | Name | Description | |-|-| | result_id | Sys_id of the test result record. | [ ] {#agnt_clnt_cll-POST-check-def-test__table_e5l_yrv_wqb} ## Agent Client Collector - POST /agents/check_instances/{check_instance_id}/test {#ariaid-title22} Enables building test check requests on check instances. Use this API for the following tasks: * Set the check instance to test * Set the configuration item to run the test against {#agnt_clnt_cll-POST-check-inst-test__ul_tdb_gpk_5qb}You can also specify one of the following identifiers to use during the test: * Credential sys_id * Credential alias id * Credential name {#agnt_clnt_cll-POST-check-inst-test__ul_tft_qwk_5qb} ### URL format /api/sn_agent/agents/check_instances/{check_instance_id}/test ### Supported request parameters {#agnt_clnt_cll-POST-check-inst-test__entry__2} | Name | Description | |-|-| | check_instance_id | Sys_id of the check definition listed in the Check Definitions \[sn_agent_check_def\] table. | [Table 122. Path parameters] {#agnt_clnt_cll-POST-check-inst-test__entry__6} | Name | Description | |-|-| | None | | [Table 123. Query parameters] {#agnt_clnt_cll-POST-check-inst-test__table_obs_krv_wqb__entry__2} | Name | Description | |-|-| | ci_id | Sys_id of a CMDB Configuration Item. | | credentials_id | Sys_id of a credentials record. | | credentials_name | Name of the credentials record. | | credentials_alias_id | Sys_id of a credentials alias record. | | credentials_alias_name | Name of a credentials alias. | | proxy_agent_id | Unique ID of an agent proxy to run this check. This value is listed in the Agent ID column of the Agent Client Collectors \[sn_agent_cmdb_ci_agent\] table. | [Table 124. Request body parameters (JSON)] {#agnt_clnt_cll-POST-check-inst-test__table_obs_krv_wqb} ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-POST-check-inst-test__entry__24}{#agnt_clnt_cll-POST-check-inst-test__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 125. Request headers] {#agnt_clnt_cll-POST-check-inst-test__entry__28} | Header | Description | |-|-| | None | | [Table 126. Response headers] ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-POST-check-inst-test__table_b2r_5gr_wqb__entry__2}{#agnt_clnt_cll-POST-check-inst-test__entry-200-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 500 | Error building the test request. | [Table 127. Status codes] {#agnt_clnt_cll-POST-check-inst-test__table_b2r_5gr_wqb} ### Response body parameters (JSON) {#agnt_clnt_cll-POST-check-inst-test__entry__38} | Name | Description | |-|-| | result_id | Sys_id of the test result record. | [ ] ## Agent Client Collector - POST /agents/update/check/{check_id} {#ariaid-title23} Updates a selected policy check. To retrieve the properties of a policy sandbox copy, use [GET /agents/policy/sandbox_from_published/{policy_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-policy-sbox-fr "Gets the sandbox copy of a published policy and provides policy details."). ### URL format /api/sn_agent/agents/update/check/{check_id} ### Supported request parameters {#agnt_clnt_cll-POST-update-check-id__section_vvx_g2z_2pb} {#agnt_clnt_cll-POST-update-check-id__table_n3g_1fs_2pb__entry__2} | Name | Description | |-|-| | check_id | Sys_id of a policy check sandbox copy in the Check Instances \[sn_agent_check\] table. Data type: String | [Table 128. Path parameters] {#agnt_clnt_cll-POST-update-check-id__table_n3g_1fs_2pb} {#agnt_clnt_cll-POST-update-check-id__table_wvx_g2z_2pb__entry__2} | Name | Description | |-|-| | None | | [Table 129. Query parameters] {#agnt_clnt_cll-POST-update-check-id__table_wvx_g2z_2pb} {#agnt_clnt_cll-POST-update-check-id__table_xvx_g2z_2pb__entry__2} | Name | Description | |-|-| | active | Flag that indicates whether the policy check is active. Valid values: * true: Policy check is active. * false: Policy check is inactive. {#agnt_clnt_cll-POST-update-check-id__ul_j2p_sdt_2pb} Data type: Boolean | | auto_generate | Flag that indicates whether to automatically generate the command with the command_prefix value. Valid values: * true: Automatically populate the command property with active parameter values. * false: Command isn't automatically generated. {#agnt_clnt_cll-POST-update-check-id__ul_myc_x2t_2pb} Data type: Boolean | | check_type | Check type specifying the monitoring option. Possible values: * Discovery: Check that locates CIs related to the agent. * Events: The check's result is transformed into an Event Management event. * Metrics: The values from the check result are transformed to metrics. {#agnt_clnt_cll-POST-update-check-id__ul_pgd_42t_2pb} Data type: String | | command | Command that the Agent Client Collector executes. Parameter taken from a template or monitored CI. Note: If auto_generate is true, this property is automatically populated with the prefix and flags of the active parameters listed in the parameters object. Data type: String | | command_prefix | If the auto_generate property is true, this command is used for automatic generation. The prefix consists of any portion of the command which is static (does not change), such as the script name. Data type: String | | event_status_change_threshold | Number of consecutive times that a check's response status must happen before a new event is sent. Returns null if not set. For example, if this value is 3, a check whose response status changes from OK to Error generates a new event with an Error status after the third consecutive occurrence of the status change. Data type: Number | | event_status_repair_threshold | Number of consecutive times that a check's response status must improve to close the previous event. Returns null if not set. For example, if this value is 3, a check whose response status changes from Error to OK closes the previous event and generates a new event with an OK status after the third consecutive occurrence of the status change. Data type: Number | | interval | Amount of time in seconds to wait between check executions. For example, a value of 60 means that the check runs every 60 seconds. Data type: Number | | name | Name of the check. Data type: String | | timeout | Amount of time, in seconds, after which the check execution stops when no output is returned. For example, a value of 60 means that when the check execution doesn't return a value for 60 seconds, the execution stops. Data type: String | [Table 130. Request body parameters (JSON)] {#agnt_clnt_cll-POST-update-check-id__table_xvx_g2z_2pb} ### Headers {#agnt_clnt_cll-POST-update-check-id__section_yvx_g2z_2pb} The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-POST-update-check-id__table_zvx_g2z_2pb__entry__2}{#agnt_clnt_cll-POST-update-check-id__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 131. Request headers] {#agnt_clnt_cll-POST-update-check-id__table_zvx_g2z_2pb} {#agnt_clnt_cll-POST-update-check-id__table_awx_g2z_2pb__entry__2} | Header | Description | |-|-| | None | | [Table 132. Response headers] {#agnt_clnt_cll-POST-update-check-id__table_awx_g2z_2pb} ### Status codes {#agnt_clnt_cll-POST-update-check-id__section_bwx_g2z_2pb} The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-POST-update-check-id__table_cwx_g2z_2pb__entry__2}{#agnt_clnt_cll-POST-update-check-id__entry-200-status-code}{#agnt_clnt_cll-POST-update-check-id__agntCC-desc-403-admin}{#agnt_clnt_cll-POST-update-check-id__entry-500-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 403 | The user does not have the agent_client_collector_admin role. | | 404 | No record found with the provided sys_id. | | 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. | [Table 133. Status codes] {#agnt_clnt_cll-POST-update-check-id__table_cwx_g2z_2pb} ### Response body parameters (JSON) {#agnt_clnt_cll-POST-update-check-id__section_dwx_g2z_2pb} {#agnt_clnt_cll-POST-update-check-id__table_ewx_g2z_2pb__entry__2} | Name | Description | |-|-| | message | Message containing operation success or failure results. Data type: String | [ ] {#agnt_clnt_cll-POST-update-check-id__table_ewx_g2z_2pb} ### cURL request {#agnt_clnt_cll-POST-update-check-id__example_fwx_g2z_2pb} The following example shows how to update the event change and repair properties of a policy check. curl "https://instance.service-now.com/api/sn_agent/agents/update/check/" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data "{ \"event_status_change_threshold\" : \"2\", \"event_status_repair_threshold\" : \"1\" }" \ --user 'username':'password' Output: { "message": "Operation was successful" } ## Agent Client Collector - POST /agents/update/check_def_params/{check_def_param_id} {#ariaid-title24} Enables changing one or more field values of a specified check parameter. ### URL format /api/sn_agent/agents/update/check_def_params/{check_def_param_id} ### Supported request parameters {#agnt_clnt_cll-POST-up-check-def-p__entry__2} | Name | Description | |-|-| | check_def_param_id | Sys_id of the check parameter. Data type: String Table: Check Parameter Definitions \[sn_agent_check_param_def\] | [Table 134. Path parameters] {#agnt_clnt_cll-POST-up-check-def-p__entry__6} | Name | Description | |-|-| | None | | [Table 135. Query parameters] {#agnt_clnt_cll-POST-up-check-def-p__table_fhm_klr_wqb__entry__2} | Name | Description | |-|-| | active | Flag that indicates whether the check parameter is active. Valid values: * true: The check parameter is active. * false: The check parameter is inactive. {#agnt_clnt_cll-POST-up-check-def-p__ul_pnb_jyc_wqb} Data type: Boolean | | default_value | Specifies the default value for this check parameter. Data type: String | | mandatory | Flag that indicates whether the check parameter is required. Valid values: * true: The check parameter is required. * false: The check parameter is optional. {#agnt_clnt_cll-POST-up-check-def-p__ul_wtg_2zc_wqb} Data type: Boolean | | name | Name of the check parameter. Data type: String | [Table 136. Request body parameters (JSON)] {#agnt_clnt_cll-POST-up-check-def-p__table_fhm_klr_wqb} Note: Refer to the data dictionary for a comprehensive list of Check Definition fields and types. ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-POST-up-check-def-p__entry__20}{#agnt_clnt_cll-POST-up-check-def-p__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 137. Request headers] {#agnt_clnt_cll-POST-up-check-def-p__entry__24} | Header | Description | |-|-| | None | | [Table 138. Response headers] ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-POST-up-check-def-p__table_tfm_ykr_wqb__entry__2}{#agnt_clnt_cll-POST-up-check-def-p__entry-200-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 404 | The check parameter was not found with sys_id provided. | | 500 | Error updating the check parameter. | [Table 139. Status codes] {#agnt_clnt_cll-POST-up-check-def-p__table_tfm_ykr_wqb} ### Response body parameters (JSON) {#agnt_clnt_cll-POST-up-check-def-p__table_t3p_kmr_wqb__entry__2} | Name | Description | |-|-| | None | Success or error message. | [ ] {#agnt_clnt_cll-POST-up-check-def-p__table_t3p_kmr_wqb} ### cURL request The following example shows how to activate a check parameter. curl "https://instance.service-now.com/api/sn_agent/agents/update/check_def_params/02d89bb01b307490f271ea42b24bcb63" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data "{\"active\":\"true\"}" \ --user 'username':'password' Output: "message": "Check Definition Parameter Updated Successfully" ## Agent Client Collector - POST /agents/update/check_def_secure_params/{check_def_secure_param_id} {#ariaid-title25} Enables changing one or more field values of a specified check secure parameter. ### URL format /api/sn_agent/agents/update/check_def_secure_params/{check_def_secure_param_id} ### Supported request parameters {#agnt_clnt_cll-POST-up-check-def-sp__entry__2} | Name | Description | |-|-| | check_def_secure_param_id | Sys_id of the secure parameter. Data type: String Table: Check Secure Parameter Definitions \[sn_agent_check_secure_param_def\] | [Table 140. Path parameters] {#agnt_clnt_cll-POST-up-check-def-sp__entry__6} | Name | Description | |-|-| | None | | [Table 141. Query parameters] {#agnt_clnt_cll-POST-up-check-def-sp__entry__10} | Name | Description | |-|-| | active | Flag that indicates whether the secure parameter is active. Valid values: * true: The secure parameter is active. * false: The secure parameter is inactive. {#agnt_clnt_cll-POST-up-check-def-sp__ul_g1b_3vc_wqb} Data type: Boolean | | name | Name of the secure parameter. Data type: String | | order | Order in which the parameter is sent to the check command/script. Data type: String | [Table 142. Request body parameters (JSON)] ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-POST-up-check-def-sp__entry__18}{#agnt_clnt_cll-POST-up-check-def-sp__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 143. Request headers] {#agnt_clnt_cll-POST-up-check-def-sp__entry__22} | Header | Description | |-|-| | None | | [Table 144. Response headers] ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-POST-up-check-def-sp__table_rst_ykr_wqb__entry__2}{#agnt_clnt_cll-POST-up-check-def-sp__entry-200-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 404 | The check secure parameter was not found with sys_id provided. | | 500 | Error updating the check secure parameter. | [Table 145. Status codes] {#agnt_clnt_cll-POST-up-check-def-sp__table_rst_ykr_wqb} ### Response body parameters (JSON) {#agnt_clnt_cll-POST-up-check-def-sp__table_lfq_5kr_wqb__entry__2} | Name | Description | |-|-| | None | Success or error message. | [ ] {#agnt_clnt_cll-POST-up-check-def-sp__table_lfq_5kr_wqb} ### cURL request The following example shows how to activate a check secure parameter. curl "https://instance.service-now.com/api/sn_agent/agents/update/check_def_secure_params/2d30a066dba530106f4810284b9619c1" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data "{\"active\":\"true\"}" \ --user 'username':'password' Output: "message": "Check Definition Secure Parameter Updated Successfully" ## Agent Client Collector - POST /agents/update/check_defs/{check_def_id} {#ariaid-title26} Enables changing one or more field values of a specified check definition. ### URL format /api/sn_agent/agents/update/check_defs/{check_def_id} ### Supported request parameters {#agnt_clnt_cll-POST-up-check-def-cd__entry__2} | Name | Description | |-|-| | check_def_id | Sys_id of the check definition listed in the Check Definitions \[sn_agent_check_def\] table. Data type: String | [Table 146. Path parameters] {#agnt_clnt_cll-POST-up-check-def-cd__entry__6} | Name | Description | |-|-| | None | | [Table 147. Query parameters] {#agnt_clnt_cll-POST-up-check-def-cd__entry__10} | Name | Description | |-|-| | active | Indicates whether this check definition is active. Valid values: * 0: This check definition is inactive. * 1: This check definition is active. {#agnt_clnt_cll-POST-up-check-def-cd__ul_gdc_4wj_wqb} Data type: Number | | background | Flag that indicates whether this check definition is a background check. A background check is a check which the agent starts execution of and doesn't wait for it to finish running. Valid values: * true: This check definition is a background check. * false: This check definition is not a background check. {#agnt_clnt_cll-POST-up-check-def-cd__ul_ypb_5ps_5qb} Data type: Boolean | | check_group | Group specified for this check definition. | | check_type | Type of check. Possible values: * Events -- Check results are transformed into an Event Management event. * Metrics -- Values from the check result are transformed to metrics. {#agnt_clnt_cll-POST-up-check-def-cd__ul_gtr_kfb_wqb} Data type: String | | command | Command that the Agent Client Collector executes. Data type: String | | name | Name of the check. Data type: String | | params | Map of parameter names and values. These settings can be used to override the parameter records of the check definition and its specified values. "params": { "": "String" } Data type: Object | | plugins | List of [Agent Client Collector plugins](https://www.servicenow.com/docs/access?context=acc-assets&version=yokohama&pubname=yokohama-it-operations-management&ft:locale=en-US) associated with this check. Data type: Array | | proxy_valid | Flag that indicates whether the check definition policy is set to work as a proxy. Valid values: * true: This check definition policy is set to work as a proxy. * false: This check definition policy is not set to work as a proxy. {#agnt_clnt_cll-POST-up-check-def-cd__ul_wbf_qps_5qb} Data type: Boolean | | query | Encoded query for retrieving the GlideRecord from the table specified in the table property. Data type: String | | table | Name of the cmdb_ci table for this check. Data type: String | | timeout | Timeout in seconds. Data type: Number | [Table 148. Request body parameters (JSON)] Note: Refer to the data dictionary for a comprehensive list of Check Definition fields and types. ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-POST-up-check-def-cd__entry__36}{#agnt_clnt_cll-POST-up-check-def-cd__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 149. Request headers] {#agnt_clnt_cll-POST-up-check-def-cd__entry__40} | Header | Description | |-|-| | None | | [Table 150. Response headers] ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-POST-up-check-def-cd__entry__44}{#agnt_clnt_cll-POST-up-check-def-cd__entry-200-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 404 | The check definition was not found with sys_id provided. | | 500 | Error updating the check definition. | [Table 151. Status codes] ### Response body parameters (JSON) {#agnt_clnt_cll-POST-up-check-def-cd__entry__52} | Name | Description | |-|-| | None | Success or error message. | [ ] ### cURL request The following example shows how to deactivate a check definition. curl "https://instance.service-now.com/api/sn_agent/agents/update/check_defs/99e12466dba530106f4810284b961976" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data "{\"active\":\"false\"}" \ --user 'username':'password' Output: "message": "Check Definition Updated Successfully" ## Agent Client Collector - POST /agents/update/check_param/{param_id} {#ariaid-title27} Updates a selected policy check parameter. To retrieve the properties of a policy sandbox copy, use [GET /agents/policy/sandbox_from_published/{policy_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-policy-sbox-fr "Gets the sandbox copy of a published policy and provides policy details."). ### URL format /api/sn_agent/agents/update/check_param/{param_id} ### Supported request parameters {#agnt_clnt_cll-POST-update-check_param__section_dvh_g2z_2pb} {#agnt_clnt_cll-POST-update-check_param__table_n3g_1fs_2pb__entry__2} | Name | Description | |-|-| | param_id | Sys_id of policy check parameter sandbox copy. Data type: String Table: Check Parameters \[sn_agent_check_param\] | [Table 152. Path parameters] {#agnt_clnt_cll-POST-update-check_param__table_n3g_1fs_2pb} {#agnt_clnt_cll-POST-update-check_param__table_evh_g2z_2pb__entry__2} | Name | Description | |-|-| | None | | [Table 153. Query parameters] {#agnt_clnt_cll-POST-update-check_param__table_evh_g2z_2pb} {#agnt_clnt_cll-POST-update-check_param__table_fvh_g2z_2pb__entry__2} | Name | Description | |-|-| | active | Flag that indicates whether the check parameter is active. Valid values: * true: Check parameter is active. * false: Check parameter is inactive. {#agnt_clnt_cll-POST-update-check_param__ul_u2x_5fv_2pb} Data type: Boolean | | flag | | | mandatory | Flag that indicates whether this check is mandatory. Valid values: * true: This check is mandatory. * false: This check is optional. {#agnt_clnt_cll-POST-update-check_param__ul_flq_qkv_2pb} Data type: Boolean | | name | Name of the parameter. Data type: String | | value | Value of the parameter. Data type: String | | value_required | Flag that indicates whether the information provided by the value property is required. Valid values: * true: The value property is required. * false: The value property is null or not required. {#agnt_clnt_cll-POST-update-check_param__ul_ug3_3jv_2pb} Data type: Boolean | [Table 154. Request body parameters (JSON)] {#agnt_clnt_cll-POST-update-check_param__table_fvh_g2z_2pb} ### Headers {#agnt_clnt_cll-POST-update-check_param__section_gvh_g2z_2pb} The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-POST-update-check_param__table_hvh_g2z_2pb__entry__2}{#agnt_clnt_cll-POST-update-check_param__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 155. Request headers] {#agnt_clnt_cll-POST-update-check_param__table_hvh_g2z_2pb} {#agnt_clnt_cll-POST-update-check_param__table_ivh_g2z_2pb__entry__2} | Header | Description | |-|-| | None | | [Table 156. Response headers] {#agnt_clnt_cll-POST-update-check_param__table_ivh_g2z_2pb} ### Status codes {#agnt_clnt_cll-POST-update-check_param__section_jvh_g2z_2pb} The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-POST-update-check_param__table_kvh_g2z_2pb__entry__2}{#agnt_clnt_cll-POST-update-check_param__entry-200-status-code}{#agnt_clnt_cll-POST-update-check_param__agntCC-desc-403-admin}{#agnt_clnt_cll-POST-update-check_param__entry-500-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 403 | The user does not have the agent_client_collector_admin role. | | 404 | No record found with the provided sys_id. | | 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. | [Table 157. Status codes] {#agnt_clnt_cll-POST-update-check_param__table_kvh_g2z_2pb} ### Response body parameters (JSON) {#agnt_clnt_cll-POST-update-check_param__section_lvh_g2z_2pb} {#agnt_clnt_cll-POST-update-check_param__table_mvh_g2z_2pb__entry__2} | Name | Description | |-|-| | message | Message containing operation success or failure results. Data type: String | [ ] {#agnt_clnt_cll-POST-update-check_param__table_mvh_g2z_2pb} ### cURL request {#agnt_clnt_cll-POST-update-check_param__example_nvh_g2z_2pb} The following example shows how to update several properties of a policy check parameter. curl "https://instance.service-now.com/api/sn_agent/agents/update/check_param/" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data "{ \"flag\" : \"-d\", \"mandatory\" : \"true\", \"name\" : \"scheme2\", \"value\" : \"120\", \"value_required\" : \"false\" }" \ --user 'username':'password' Output: { "message": "Operation was successful" } ## Agent Client Collector - POST /agents/update/check_secure_param/{param_id} {#ariaid-title28} Updates a selected policy check secure parameter. To retrieve the properties of a policy sandbox copy, use [GET /agents/policy/sandbox_from_published/{policy_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-policy-sbox-fr "Gets the sandbox copy of a published policy and provides policy details."). ### URL format /api/sn_agent/agents/update/check_secure_param/{param_id} ### Supported request parameters {#agnt_clnt_cll-POST-update-check_secure__section_dzx_f2z_2pb} {#agnt_clnt_cll-POST-update-check_secure__table_n3g_1fs_2pb__entry__2} | Name | Description | |-|-| | param_id | Sys_id of the policy check secure parameter sandbox copy. Data type: String Table: Check Secure Parameter \[sn_agent_check_secure_param\] | [Table 158. Path parameters] {#agnt_clnt_cll-POST-update-check_secure__table_n3g_1fs_2pb} {#agnt_clnt_cll-POST-update-check_secure__table_ezx_f2z_2pb__entry__2} | Name | Description | |-|-| | None | | [Table 159. Query parameters] {#agnt_clnt_cll-POST-update-check_secure__table_ezx_f2z_2pb} {#agnt_clnt_cll-POST-update-check_secure__table_fzx_f2z_2pb__entry__2} | Name | Description | |-|-| | active | Flag that indicates whether the check secure parameter is active. Valid values: * true: The check secure parameter is active. * false: The check secure parameter is inactive. {#agnt_clnt_cll-POST-update-check_secure__ul_xwy_vfv_2pb} Data type: Boolean | | name | Name of the secure parameter. Data type: String | | order | Order in which the parameter is sent to the check command/script. Data type: Number | [Table 160. Request body parameters (JSON)] {#agnt_clnt_cll-POST-update-check_secure__table_fzx_f2z_2pb} ### Headers {#agnt_clnt_cll-POST-update-check_secure__section_gzx_f2z_2pb} The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-POST-update-check_secure__table_hzx_f2z_2pb__entry__2}{#agnt_clnt_cll-POST-update-check_secure__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 161. Request headers] {#agnt_clnt_cll-POST-update-check_secure__table_hzx_f2z_2pb} {#agnt_clnt_cll-POST-update-check_secure__table_izx_f2z_2pb__entry__2} | Header | Description | |-|-| | None | | [Table 162. Response headers] {#agnt_clnt_cll-POST-update-check_secure__table_izx_f2z_2pb} ### Status codes {#agnt_clnt_cll-POST-update-check_secure__section_jzx_f2z_2pb} The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-POST-update-check_secure__table_kzx_f2z_2pb__entry__2}{#agnt_clnt_cll-POST-update-check_secure__entry-200-status-code}{#agnt_clnt_cll-POST-update-check_secure__agntCC-desc-403-admin}{#agnt_clnt_cll-POST-update-check_secure__entry-500-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 403 | The user does not have the agent_client_collector_admin role. | | 404 | No record found with the provided sys_id. | | 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. | [Table 163. Status codes] {#agnt_clnt_cll-POST-update-check_secure__table_kzx_f2z_2pb} ### Response body parameters (JSON) {#agnt_clnt_cll-POST-update-check_secure__section_lzx_f2z_2pb} {#agnt_clnt_cll-POST-update-check_secure__table_mzx_f2z_2pb__entry__2} | Name | Description | |-|-| | message | Message containing operation success or failure results. Data type: String | [ ] {#agnt_clnt_cll-POST-update-check_secure__table_mzx_f2z_2pb} ### cURL request {#agnt_clnt_cll-POST-update-check_secure__example_nzx_f2z_2pb} The following example shows how to update the properties of a policy check secure parameter. curl "https://instance.service-now.com/api/sn_agent/agents/update/check_secure_param/" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data "{ \"name\" : \"new name\", \"order\" : \"2\" }" \ --user 'username':'password' Output: { "message": "Operation was successful" } ## Agent Client Collector - POST /agents/update/policy/{policy_id} {#ariaid-title29} Updates a sandbox copy of a policy. To retrieve the properties of a policy sandbox copy, use [GET /agents/policy/sandbox_from_published/{policy_id}](https://www.servicenow.com/docs/6cJ7lYvsemc258yF6JbOew#agnt_clnt_cll-GET-policy-sbox-fr "Gets the sandbox copy of a published policy and provides policy details."). ### URL format /api/sn_agent/agents/update/policy/{policy_id} ### Supported request parameters {#agnt_clnt_cll-POST-update-policy__table_n3g_1fs_2pb__entry__2} | Name | Description | |-|-| | policy_id | Sys_id of a policy sandbox copy. Data type: String Table: Policies \[sn_agent_policy\] | [Table 164. Path parameters] {#agnt_clnt_cll-POST-update-policy__table_n3g_1fs_2pb} {#agnt_clnt_cll-POST-update-policy__entry__6} | Name | Description | |-|-| | None | | [Table 165. Query parameters] {#agnt_clnt_cll-POST-update-policy__entry__10} | Name | Description | |-|-| | cred_alias | Credential name. Data type: String Table: Credentials \[discovery_credentials\] | | credential_alias | Sys_id of the credential alias. Data type: String Table: Connection \& Credential Aliases \[sys_alias\] | | filter | Filter restricting the policy's checks to monitor only the specified criteria. Data type: String | | interval | Amount of time in seconds to wait between policy checks. For example, a value of 60 means that the check runs every 60 seconds. Note: The value of the checks.interval property overrides the value configured in this field. Data type: Number | | monitored_ci_group | Name of the [CMDB groups](https://www.servicenow.com/docs/access?context=cmdb-groups&version=yokohama&pubname=yokohama-servicenow-platform&ft:locale=en-US) associated with the policy. This field is only applied if the value of the monitored_ci_type_group property is true. Data type: String Table: CMDB Groups \[cmdb_group\] | | monitored_ci_script | Script for monitoring CIs. This field is only applied if the value of the policies.monitored_ci_type_script property is true. Data type: String | | monitored_ci_type_filter | Flag that indicates whether filtering by CI type is enabled. The CI type is listed in the table property. Valid values: * true: Filtering by checks group is enabled. * false: Filtering by checks group is disabled. {#agnt_clnt_cll-POST-update-policy__ul_tvm_fvt_2pb} Data type: Boolean | | monitored_ci_type_group | Flag that indicates whether monitoring by CMDB group type is enabled. Valid values: * true: CMDB group type is enabled. * false: CMDB group type is disabled. {#agnt_clnt_cll-POST-update-policy__ul_jrc_fvt_2pb} Data type: Boolean | | monitored_ci_type_script | Flag that indicates whether the script for monitoring CIs is enabled. Valid values: * true: Script for monitoring CIs is enabled. * false: Script for monitoring CIs is disabled. {#agnt_clnt_cll-POST-update-policy__ul_bs4_3wt_2pb} Data type: Boolean | | name | Name of the policy. Data type: String | | table | Monitored CI-type field on the policy. This field is only applied if monitored_ci_type_filter is true. Data type: String | [Table 166. Request body parameters (JSON)] ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-POST-update-policy__entry__34}{#agnt_clnt_cll-POST-update-policy__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 167. Request headers] {#agnt_clnt_cll-POST-update-policy__entry__38} | Header | Description | |-|-| | None | | [Table 168. Response headers] ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#agnt_clnt_cll-POST-update-policy__entry__42}{#agnt_clnt_cll-POST-update-policy__entry-200-status-code}{#agnt_clnt_cll-POST-update-policy__agntCC-desc-403-admin}{#agnt_clnt_cll-POST-update-policy__entry-500-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 403 | The user does not have the agent_client_collector_admin role. | | 404 | No record found with the provided sys_id. | | 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. | [Table 169. Status codes] ### Response body parameters (JSON) {#agnt_clnt_cll-POST-update-policy__entry__52} | Name | Description | |-|-| | message | Message containing operation success or failure results. Data type: String | [ ] ### cURL request The following example shows how to update the name and filter properties/fields of a policy. curl "https://instance.service-now.com/api/sn_agent/agents/update/policy/" \--request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data "{ \"name\" : \"new policy name\", \"filter\" : \"operational_status=1\" }" \ --user 'username':'password' Output: { "message": "Operation was successful" }