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.
Agent management endpoints

For information on performing similar tasks in a script include, see .

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. 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}. Use the sys_ids from this response to modify properties using an update endpoint.
  2. Modify policy details using an update endpoint.
  3. Publish the policy using GET /agents/policy/publish/{policy_id}.
Once published, the policy becomes Active. This API also includes endpoints for activating or deactivating a published policy:

Agent Client Collector - GET /agents/{agent_id}

Gets the information of a specified agent.

URL format

/api/sn_agent/agents/{agent_id}

Supported request parameters

Table 1. Path parameters
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 2. Query parameters
Name Description
None
Table 3. Request body parameters (JSON)
Name Description
None

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.

Table 4. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 5. Response headers
Header Description
None

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.

Table 6. Status codes
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.

Response body parameters (JSON)

Example: cURL request

The following example shows how to get agent details.

curl "https://instance.service-now.com/api/sn_agent/agents/<agent_id>" \
--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

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

/api/sn_agent/agents/{agent_id}/data/off

Supported request parameters

Table 7. Path parameters
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 8. Query parameters
Name Description
None
Table 9. Request body parameters (JSON)
Name Description
None

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.

Table 10. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 11. Response headers
Header Description
None

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.

Table 12. Status codes
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.

Response body parameters (JSON)

Name Description
message Message containing operation success or failure results.

Data type: String

Example: cURL request

The following example shows how to turn off agent data collection.

curl "https://instance.service-now.com/api/sn_agent/agents/<agent_id>/data/off" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

Output:

{
"message": "Data Collection Disabled For Agent With ID: <agent_id>"
}

Agent Client Collector - GET /agents/{agent_id}/data/on

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

/api/sn_agent/agents/{agent_id}/data/on

Supported request parameters

Table 13. Path parameters
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 14. Query parameters
Name Description
None
Table 15. Request body parameters (JSON)
Name Description
None

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.

Table 16. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 17. Response headers
Header Description
None

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.

Table 18. Status codes
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.

Response body parameters (JSON)

Name Description
message Message containing operation success or failure results.

Data type: String

Example: cURL request

The following example shows how to turn on agent data collection.

curl "https://instance.service-now.com/api/sn_agent/agents/<agent_id>/data/on" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

Output:

{
  "message": "Data Collection Enabled For Agent With ID: <agent_id>"
}

Agent Client Collector - GET /agents/{agent_id}/discovery

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

Table 19. Path parameters
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 20. Query parameters
Name Description
None
Table 21. Request body parameters (JSON)
Name Description
None

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.

Table 22. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 23. Response headers
Header Description
None

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.

Table 24. Status codes
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.

Response body parameters (JSON)

Name Description
message Message containing operation success or failure results.

Data type: String

Example: 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/<agent_id>/discovery" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

Output:

{
  "message": "Running Discovery For Agent With ID: <agent_id>"
}

Agent Client Collector - GET /agents/check_defs/{check_def_id}

Gets a specified check definition with details.

URL format

/api/sn_agent/agents/check_defs/{check_def_id}

Supported request parameters

Table 25. Path parameters
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 26. Query parameters
Name Description
None
Table 27. Request body parameters (JSON)
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.

Data type: Boolean

Default: False

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.

Table 28. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 29. Response headers
Header Description
None

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.

Table 30. Status codes
Status code Description
200 Successful. The request was successfully processed.
404 Check definition was not found with the sys_id provided.

Response body parameters (JSON)

Example: 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

Gets a list of check definitions with details.

URL format

/api/sn_agent/agents/check_defs/list

Supported request parameters

Table 31. Path parameters
Name Description
None
Table 32. Query parameters
Name Description
None
Table 33. Request body parameters (JSON)
Name Description
X-Enc-Query An encoded query string 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.

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

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.

Table 34. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 35. Response headers
Header Description
None

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.

Table 36. Status codes
Status code Description
200 Successful. The request was successfully processed.

Response body parameters (JSON)

Example: 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}

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

Table 37. Path parameters
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 38. Query parameters
Name Description
None
Table 39. Request body parameters (JSON)
Name Description
None

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.

Table 40. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 41. Response headers
Header Description
None

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.

Table 42. Status codes
Status code Description
200 Successful. The request was successfully processed.
404 The request with the ID provided is not found.

Response body parameters (JSON)

Name Description
None

Example: 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}

Gets status of the request with the given ID.

URL format

/api/sn_agent/agents/exec/run/{request_id}

Supported request parameters

Table 43. Path parameters
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 44. Query parameters
Name Description
None
Table 45. Request body parameters (JSON)
Name Description
None

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.

Table 46. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 47. Response headers
Header Description
None

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.

Table 48. Status codes
Status codeDescription
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.

Response body parameters (JSON)

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.

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.

Data type: String

Example: 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}

Gets the test check status of the given test result.

URL format

/api/sn_agent/agents/exec/test/{test_result_id}

Supported request parameters

Table 49. Path parameters
Name Description
test_result_id A test result ID generated by creating a test check request.
Table 50. Query parameters
Name Description
None
Table 51. Request body parameters (JSON)
Name Description
None

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.

Table 52. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 53. Response headers
Header Description
None

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.

Response body parameters (JSON)

Properties Description
status Status of the test results.
Possible values:
  • 0: Pending
  • 1: In progress
  • 2: Complete
  • 3: No test result with given ID

Data type: String
output Output describing the status.

Data type: String

Example: 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

Gets a list of agents with related information.

URL format

/api/sn_agent/agents/list

Supported request parameters

Table 55. Path parameters
Name Description
None
Table 56. Query parameters
Name Description
None
Table 57. Request body parameters (JSON)
Name Description
None

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.

Table 58. Request headers
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.
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 59. Response headers
Header Description
None

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.

Table 60. Status codes
Status code Description
200 Successful. The request was successfully processed.
403 The user does not have the agent_client_collector_user role.

Response body parameters (JSON)

Example: 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"
     }
   ]
}

Example: cURL request

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

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

/api/sn_agent/agents/{agent_id}/log

Supported request parameters

Table 61. Path parameters
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 62. Query parameters
Name Description
None
Table 63. Request body parameters (JSON)
Name Description
None

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.

Table 64. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 65. Response headers
Header Description
None

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.

Table 66. Status codes
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.

Response body parameters (JSON)

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

Example: cURL request

The following example shows how to get a log request ID.

curl "https://instance.service-now.com/api/sn_agent/agents/<sys_id>/log" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

Output:

"request_id": "<sys_id>"

Agent Client Collector - GET /agents/log/{request_id}/

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

Table 67. Path parameters
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 68. Query parameters
Name Description
None
Table 69. Request body parameters (JSON)
Name Description
None

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.

Table 70. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 71. Response headers
Header Description
None

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.

Table 72. Status codes
Status codeDescription
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.

Response body parameters (JSON)

Properties Description
output Information describing the status.

Example: 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_ID>" \
--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

Gets a list of policies that are in published or unpublished draft state.

URL format

/api/sn_agent/agents/policies/list

Supported request parameters

Table 73. Path parameters
Name Description
None
Table 74. Query parameters
Name Description
None
Table 75. Request body parameters (JSON)
Name Description
None

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.

Table 76. Request headers
HeaderDescription
Accept Data format of the response body. Only supports application/json.
X-Enc-Query Optional. Encoded query string in standard Glide format. See Encoded query strings.
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.

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.

Default: false

Data type: Boolean
Table 77. Response headers
Header Description
None

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.

Table 78. Status codes
Status code Description
200 Successful. The request was successfully processed.
403 The user does not have the agent_client_collector_user role.

Response body parameters (JSON)

Example: cURL request

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}

Activates a published policy.

For a list of published policies, use GET /agents/policies/list. 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

Table 80. Path parameters
Name Description
policy_id Sys_id of the published policy.

Data type: String

Table: Policies [sn_agent_policy]
Table 81. Query parameters
Name Description
None
Table 82. Request body parameters (JSON)
Name Description
None

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.

Table 83. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 84. Response headers
Header Description
None

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.

Table 85. Status codes
Status codeDescription
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.

Response body parameters (JSON)

Header Description
message Message containing operation success or failure results.

Data type: String

Example: cURL request

The following example shows how to activate a policy.

curl "https://instance.service-now.com/api/sn_agent/agents/policy/activate/<sys_id>" \
--request GET \
--header "Accept:application/json" \
--user 'username' : 'password'

Output:

{
  "message": "Operation was successful"
}

Agent Client Collector - GET /agents/policy/deactivate/{policy_id}

Deactivates a published policy.

For a list of published policies, use GET /agents/policies/list. 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

Table 86. Path parameters
Name Description
policy_id Sys_id of the published policy.

Data type: String

Table: Policies [sn_agent_policy]
Table 87. Query parameters
Name Description
None
Table 88. Request body parameters (JSON)
Name Description
None

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.

Table 89. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 90. Response headers
Header Description
None

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.

Table 91. Status codes
Status codeDescription
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.

Response body parameters (JSON)

Header Description
message Message containing operation success or failure results.

Data type: String

Example: cURL request

The following example shows how to deactivate a policy.

curl "https://instance.service-now.com/api/sn_agent/agents/policy/deactivate/<sys_id>" \
--request GET \
--header "Accept:application/json" \
--user 'username' : 'password'

Output:

{
  "message": "Operation was successful"
}

Agent Client Collector - GET /agents/policy/publish/{policy_id}

Publishes a draft policy.

Use any of the following endpoints to modify a draft or sandbox copy prior to publishing:

URL format

/api/sn_agent/agents/policy/publish/{policy_id}

Supported request parameters

Table 92. Path parameters
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.

Data type: String
Table 93. Query parameters
Name Description
None
Table 94. Request body parameters (JSON)
Name Description
None

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.

Table 95. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 96. Response headers
Header Description
None

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.

Table 97. Status codes
Status codeDescription
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.

Response body parameters (JSON)

Header Description
message Message containing operation success or failure results.

Data type: String

Example: cURL request

The following example shows how to publish a policy.

curl "https://instance.service-now.com/api/sn_agent/agents/policy/publish/<sys_id>" \
--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}

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:

For a list of published policies, use GET /agents/policies/list. 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

Table 98. Path parameters
Name Description
policy_id Sys_id of the published policy.

Data type: String

Table: Policies [sn_agent_policy]
Table 99. Query parameters
Name Description
None
Table 100. Request body parameters (JSON)
Name Description
None

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.

Table 101. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 102. Response headers
Header Description
None

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.

Table 103. Status codes
Status codeDescription
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.

Response body parameters (JSON)

Example: 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/<sys_id>" \
--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

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

URL format

/api/sn_agent/agents/{agent_id}/restart

Supported request parameters

Table 104. Path parameters
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 105. Query parameters
Name Description
None
Table 106. Request body parameters (JSON)
Name Description
None

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.

Table 107. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 108. Response headers
Header Description
None

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.

Table 109. Status codes
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.

Response body parameters (JSON)

Name Description
message Message containing operation success or failure results.

Data type: String

Example: cURL request

The following example shows how to restart an agent.

curl "https://instance.service-now.com/api/sn_agent/agents/<agent_id>/restart" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

Output:

{
  "message": "Restarting Agent With ID: <agent_id>"
}

Agent Client Collector - POST /agents/check_defs/{check_def_id}/run

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

Table 110. Path parameters
Name Description
check_def_id Sys_id of a check definition in the Check Definitions [sn_agent_check_def] table.
Table 111. Query parameters
Name Description
None
Table 112. Request body parameters (JSON)
NameDescription
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": {
  "<parameter name>": "String"
}

Data type: Object
priority Priority of the request to be set on the ECC queue.
Possible values:
  • 0: interactive
  • 1: expedited
  • 2: standard

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

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.

Table 113. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 114. Response headers
Header Description
None

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.

Table 115. Status codes
Status codeDescription
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.

Response body parameters (JSON)

Name Description
requestId Sys_id of the generated background check request.

Example: cURL request

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

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
You can also specify one of the following identifiers to use during the test:
  • Credential sys_id
  • Credential alias id
  • Credential name

URL format

/api/sn_agent/agents/check_defs/{check_def_id}/test

Supported request parameters

Table 116. Path parameters
Name Description
check_def_id Sys_id of the check definition listed in the Check Definitions [sn_agent_check_def] table.
Table 117. Query parameters
Name Description
None

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.

Table 119. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 120. Response headers
Header Description
None

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.

Table 121. Status codes
Status code Description
200 Successful. The request was successfully processed.
500 Error building the test request.

Response body parameters (JSON)

Name Description
result_id Sys_id of the test result record.

Agent Client Collector - POST /agents/check_instances/{check_instance_id}/test

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
You can also specify one of the following identifiers to use during the test:
  • Credential sys_id
  • Credential alias id
  • Credential name

URL format

/api/sn_agent/agents/check_instances/{check_instance_id}/test

Supported request parameters

Table 122. Path parameters
Name Description
check_instance_id Sys_id of the check definition listed in the Check Definitions [sn_agent_check_def] table.
Table 123. Query parameters
Name Description
None
Table 124. Request body parameters (JSON)
NameDescription
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.

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.

Table 125. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 126. Response headers
Header Description
None

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.

Table 127. Status codes
Status code Description
200 Successful. The request was successfully processed.
500 Error building the test request.

Response body parameters (JSON)

Name Description
result_id Sys_id of the test result record.

Agent Client Collector - POST /agents/update/check/{check_id}

Updates a selected policy check.

To retrieve the properties of a policy sandbox copy, use GET /agents/policy/sandbox_from_published/{policy_id}.

URL format

/api/sn_agent/agents/update/check/{check_id}

Supported request parameters

Table 128. Path parameters
Name Description
check_id Sys_id of a policy check sandbox copy in the Check Instances [sn_agent_check] table.

Data type: String
Table 129. Query parameters
Name Description
None
Table 130. Request body parameters (JSON)
NameDescription
active Flag that indicates whether the policy check is active.
Valid values:
  • true: Policy check is active.
  • false: Policy check is inactive.

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.

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.

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

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.

Table 131. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 132. Response headers
Header Description
None

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.

Table 133. Status codes
Status codeDescription
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.

Response body parameters (JSON)

Name Description
message Message containing operation success or failure results.

Data type: String

Example: cURL request

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/<check_sys_id>" \
--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}

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

Table 134. Path parameters
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 135. Query parameters
Name Description
None
Table 136. Request body parameters (JSON)
NameDescription
active Flag that indicates whether the check parameter is active.
Valid values:
  • true: The check parameter is active.
  • false: The check parameter is inactive.

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.

Data type: Boolean
name Name of the check parameter.

Data type: String
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.

Table 137. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 138. Response headers
Header Description
None

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.

Table 139. Status codes
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.

Response body parameters (JSON)

Name Description
None Success or error message.

Example: 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}

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

Table 140. Path parameters
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 141. Query parameters
Name Description
None
Table 142. Request body parameters (JSON)
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.

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

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.

Table 143. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 144. Response headers
Header Description
None

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.

Table 145. Status codes
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.

Response body parameters (JSON)

Name Description
None Success or error message.

Example: 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}

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

Table 146. Path parameters
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 147. Query parameters
Name Description
None
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.

Table 149. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 150. Response headers
Header Description
None

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.

Table 151. Status codes
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.

Response body parameters (JSON)

Name Description
None Success or error message.

Example: 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}

Updates a selected policy check parameter.

To retrieve the properties of a policy sandbox copy, use GET /agents/policy/sandbox_from_published/{policy_id}.

URL format

/api/sn_agent/agents/update/check_param/{param_id}

Supported request parameters

Table 152. Path parameters
Name Description
param_id Sys_id of policy check parameter sandbox copy.

Data type: String

Table: Check Parameters [sn_agent_check_param]
Table 153. Query parameters
Name Description
None
Table 154. Request body parameters (JSON)
NameDescription
active Flag that indicates whether the check parameter is active.
Valid values:
  • true: Check parameter is active.
  • false: Check parameter is inactive.

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.

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.

Data type: Boolean

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.

Table 155. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 156. Response headers
Header Description
None

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.

Table 157. Status codes
Status codeDescription
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.

Response body parameters (JSON)

Name Description
message Message containing operation success or failure results.

Data type: String

Example: cURL request

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/<param_sys_id>" \
--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}

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}.

URL format

/api/sn_agent/agents/update/check_secure_param/{param_id}

Supported request parameters

Table 158. Path parameters
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 159. Query parameters
Name Description
None
Table 160. Request body parameters (JSON)
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.

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

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.

Table 161. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 162. Response headers
Header Description
None

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.

Table 163. Status codes
Status codeDescription
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.

Response body parameters (JSON)

Name Description
message Message containing operation success or failure results.

Data type: String

Example: cURL request

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/<param_sys_id>" \
--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}

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}.

URL format

/api/sn_agent/agents/update/policy/{policy_id}

Supported request parameters

Table 164. Path parameters
Name Description
policy_id Sys_id of a policy sandbox copy.

Data type: String

Table: Policies [sn_agent_policy]
Table 165. Query parameters
Name Description
None

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.

Table 167. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 168. Response headers
Header Description
None

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.

Response body parameters (JSON)

Name Description
message Message containing operation success or failure results.

Data type: String

Example: 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/<policy_sys_id>" \--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"
}