
ITSI REST API reference
The ITSI REST API is recommended for administrators and developers with REST API experience only. All POST and DELETE operations are irreversible.
This reference describes ITSI REST API endpoints exposed via the splunkd
management port, 8089. You can use this API to interact programmatically and extend the functionality of Splunk IT Service Intelligence (ITSI).
For information on the Splunk platform REST API, see the Splunk REST API User Manual.
ITSI REST API usage details
Before using the ITSI REST API, consider the following:
- Use the splunkd management port, 8089, and secure HTTPS protocol.
https://localhost:8089/servicesNS/...
- Only the latest version of ITSI is supported for all APIs. Either don't specify a version or specify
vLatest
after the interface name./servicesNS/<user>/<app>/itoa_interface/vLatest/....
- The API performs capability and RBAC checks. For capability requirements, see Configure users and roles in ITSI.
- In most cases,
<user>
isnobody
and<app>
isSA-ITOA
. -
splunkd
core settings for compression, payload limits, and so on inweb.conf
apply to endpoints.
How to use the filter parameter
The ITSI REST API uses the MongoDB syntax of rules expressions to filter the payload.
Example 1: Use filter to lookup an object with title field "Web Service."
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/service?fields='title'\&filter='\{"title":"Web+Service"\}'
See db.collection.find in the MongoDB reference manual.
Example 2: Use filter to do wildcard lookup against the REST API.
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/<object_type>?fields='<field_name1>,<field_name2>'\&filter='\{"<field_name>":\{"$regex":".*"\}\}'
See $regex in the MongoDB reference manual.
How to use the rest
command for SA-ITOA endpoints
You can use the | rest
command to perform REST operations within Splunk Web. The rest
command has some arguments that differ from those accepted by REST API endpoints. For example, the limit
argument for endpoints is replaced with the count
argument when using the rest
command, so \?limit\=1
would be replaced with count=1
To see all available arguments for the rest
command and usage examples, see rest
in the Splunk Enterprise Search Reference.
As of version 4.4.0, in order to continue using | rest
for SA-ITOA endpoints, you must add report_as=text
to your Splunk searches. Otherwise those searches will stop working. For more information, see Removed features in Splunk IT Service Intelligence.
Endpoint interface categories
ITSI REST API endpoints are organized into the following interface categories, based on the scenarios they target.
Category | Description |
---|---|
ITOA Interface | Performs operations on core ITSI objects (entities, services, service templates, deep dives, and so on). |
Event Management Interface | Performs operations on ITSI event management objects. |
Maintenance Services Interface | Performs operations on ITSI maintenance service objects. |
Backup Restore Interface | Performs operations on ITSI backup and restore jobs. |
Glass table icon interface | Performs operations on ITSI glass table icons stored in the KV store. |
ITSI object data structures
For detailed information on ITSI object data structures, see the ITSI REST API schema in this manual.
ITOA Interface
This interface encapsulates operations on the following ITSI object types:
- team
- entity
- service
- base_service_template (service template)
- kpi_base_search
- deep_dive
- glass_table
- home_view (service analyzer)
- kpi_template
- kpi_threshold_template
- event_management_state
- entity_filter_rule
Base URL
https://<splunk server like localhost>:<splunkd port like 8089>/servicesNS/<user>/<app>/itoa_interface
itoa_interface/get_supported_object_types
Gets the list of supported object types in the ITOA interface.
GET
Gets list of supported object types.
Request parameters
None.
Data payload
None.
Return
List of object types.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/get_supported_object_types
JSON Response
[ "team", "entity", "service", "base_service_template", "kpi_base_search", "deep_dive", "glass_table", "home_view", "kpi_template", "kpi_threshold_template", "event_management_state", "entity_relationship", "entity_relationship_rule" "entity_filter_rule" ]
Note: The entity_relationship
and entity_relationship_rule
objects are not used.
itoa_interface/<object_type>
API to perform bulk CRUD operations on ITSI objects and single object create.
GET
Gets a list of objects by object type.
Request parameters
Name | Type | Description |
---|---|---|
sort_key | String | Name of field to sort by. |
sort_dir | Number | 1 for ascending and 0 for descending. |
limit | Number | Maximum number of entries to throttle at. |
offset | Number | specifies number n where n is the number of entries to skip from the start. Used primarily for paging. |
fields | String | Comma separated list of field names to select from the results. |
filter | String | MongoDB syntax of rules expressions to filter the payload. See How to use the filter parameter.
Make sure to use the correct filter syntax. Incorrect filter syntax will cause all rows to be returned for the object type. |
Data payload:
None.
Return
List of objects queried.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/entity/?fields='title,_key''&'filter='\{"title":\{"$regex":".*mysql"\}\}'
JSON Response
[ { "_key":"00a2f562-19ad-4398-8f12-918bc04a372b", "title":"mysql-04", "object_type":"entity" }, { "_key":"5a0084fd-a090-42fa-9283-0bbe5080429c", "title":"mysql-02", "object_type":"entity" }, { "_key":"f4f15da4-9124-4cc3-94b5-edc810d69738", "title":"mysql-03", "object_type":"entity", "sec_grp":"default_itsi_security_group" } ]
POST
Create new objects by object type.
Request parameters
None.
Data payload:
Must be a dictionary of valid schema for the object type. See ITSI REST API schema.
Return
Object identifier for object created.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/entity -H "Content-Type: application/json" -X POST -d '{"component": ["PerProcess"],"informational": {"fields": ["info"],"values": ["field"]},"_version": "3.0.0","title": "PerProcess","object_type": "entity","_type":"entity","identifier": {"fields": ["component"],"values": ["PerProcess"]}}'
JSON Response
{ "_key":"8b12efff-d81d-409e-8607-35d504e7b4a1" }
DELETE
Delete objects by object type.
Request parameters
Name | Type | Description |
---|---|---|
sort_key | String | Name of field to sort by. |
sort_dir | Number | 1 for ascending and 0 for descending. |
limit | Number | Maximum number of entries to throttle at. |
offset | Number | specifies number n where n is the number of entries to skip from the start. Used primarily for paging. |
fields | String | Comma separated list of field names to select from the results. |
filter | Number | Mongodb syntax of rules expressions to filter the payload. See How to use the filter parameter. |
Return
None.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/entity?fields='title''&'filter='\{"title":"bar"\}' -X DELETE
To prevent accidental deletion of good data, make sure to use the correct filter syntax. Incorrect filter syntax will cause all rows to be deleted for the object type. A better method for deletion is to use an object identifier, such as "60d9300f-0942-4bda-bdec-5ad4baf633b6", rather than a filter.
JSON Response
itoa_interface/<object _type>/bulk_update
API to bulk create/update ITOA interface object types such as entities.
POST
Update object identifier for the object type.
Request parameters
Name | Type | Description |
---|---|---|
is_partial_data | Number | 1 if payload for update is partial payload, 0 or default indicates entire payload for the object schema provided. 0 or default overwrites an existing object. |
Data payload
Must be a dictionary of valid schema for the object type. See ITSI REST API schema.
Return
Object identifier for updated object.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/entity/bulk_update?is_partial_data=1 -H "Content-Type: application/json" -X POST -d '[\{"_key": "id", "description": "foo"}]'
JSON Response
{ "_key":"id" }
itoa_interface/<object_type>/<object identifier>
API to perform CRUD operations on single ITSI object. The object identifier is the value populated in the _key
field which is returned in the REST call in API for create. For example: "_key" : "60d9300f-0942-4bda-bdec-5ad4baf633b6".
GET
Get object identifier for the object type.
Request parameters
None.
Data payload
None.
Return
List of objects querried.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/entity?filter='\{"title":"bar"\}'
JSON Response
{ "description":"", "mod_source":"REST", "title":"mysql-04", "services":[ { "_key":"92eae0d1-7ea0-4d52-8500-d6c19bd48dfa", "title":"Database Service" }, { "_key":"95c99846-404f-4c92-9923-2a8c8594bff1", "title":"Buttercup Store" } ], "create_by":"nobody", "mod_by":"nobody", "create_time":"2016-12-21T21:55:25.549653+00:00", "identifier":{ "fields":[ "host" ], "values":[ "mysql-04" ] }, "identifying_name":"mysql-04", "_key":"00a2f562-19ad-4398-8f12-918bc04a372b", "mod_timestamp":"2017-04- 15T00:20:21.651660+00:00", "host":[ "mysql-04" ], "_version":"2.6.0", "_type":"entity", "test":[ "true" ], "itsi_role":[ "operating_system_host" ], "_user":"nobody", "informational":{ "fields":[ "itsi_role", "test" ], "values":[ "operating_system_host", "true" ] }, "object_type":"entity", "create_source":"unknown", "mod_time":"2017-04-14 17:20:03.610566", "sec_grp":"default_itsi_security_group" }
POST
Update object identifier for the object type.
Request parameters
Name | Type | Description |
---|---|---|
is_partial_data | Number | 1 if payload for update is partial payload, 0 or default indicates entire payload for the object schema provided. 0 or default overwrites the existing object. |
Data payload
Must be a dictionary of valid schema for the object type. See ITSI REST API schema.
Return
Object identifier for updated object.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/entity/<object identifier>/?is_partial_data=1 -X POST -H "Content-Type:application/json" -d '{"description": "foo"}'
JSON Response
{ "_key":"8b12efff-d81d-409e-8607-35d504e7b4a1" }
DELETE
Delete object identifiers for the object type.
Request parameters
None.
Return
None.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/entity/60d9300f-0942-4bda-bdec-5ad4baf633b6 -X DELETE
To prevent accidental deletion of entities, do not use a filter. Incorrect filter syntax will cause all entities to be deleted.
JSON Response
None.
itoa_interface/<object_type>/count
API to get count of objects of an object type.
GET
Get count of objects of an object type.
Request parameters
Name | Type | Description |
---|---|---|
filter | String | MongoDB syntax of rules expressions to filter the objects. See How to use the filter parameter.
If no filter is specified, "all" is assumed. |
Return
Count of objects of the object type, that match the filter criteria if provided or get count of all.
Example request and response
curl -k -u admin:password https://localhost.com:8089/servicesNS/nobody/SA-ITOA/itoa_interface/entity/count/?fields='title''&'filter='\{"title":\{"$regex":".*mysql"\}\}'
JSON Response
{ "count":3 }
itoa_interface/<object_type>/<object identifier>/templatize
API to generate a template from an existing ITSI object. Only service and KPI base search objects are supported. You can use the template to replicate the object configuration into other objects.
GET
Get template from existing ITSI object.
Request parameters
None.
Data payload
None.
Return
A dictionary with the template derived from the ITSI object.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/entity/<object identifier>/templatize
JSON Response
{ "title":"External Authorization Services", "service_template_id":"", "sec_grp":"default_itsi_security_group", "enabled":1, "_version":"2.5.0", "services_depends_on":[ ], "tags":[ ], "object_type":"service", "serviceTemplateId":[ ], "kpis":[ { "tz_offset":null, "backfill_earliest_time":"-7d", "alert_on":"both", "entity_statop":"avg", "datamodel_filter":[ ], "entity_id_fields":"", "urgency":"11", "service_id":"0e11bf81-9bdf-4d95-b92b-6318631d538b", "datamodel":{ "object":"", "datamodel":"", "field":"", "owner_field":"" }, "target":"", "gap_severity_color_light":"#EEEEEE", "title":"ServiceHealthScore", "kpi_base_search":"", "threshold_field":"aggregate", "search_type":"adhoc", "entity_thresholds":{ "isMinStatic":true, "gaugeMin":0, "gaugeMax":100, "metricField":"count", "renderBoundaryMin":0, "baseSeverityValue":2, "renderBoundaryMax":100, "baseSeverityColor":"#99D18B", "search":"", "baseSeverityColorLight":"#DCEFD7", "thresholdLevels":[ { "severityValue":6, "thresholdValue":0, "severityColorLight":"#E5A6A6", "severityColor":"#B50101", "severityLabel":"critical" }, { "severityValue":5, "thresholdValue":20, "severityColorLight":"#FBCBB9", "severityColor":"#F26A35", "severityLabel":"high" }, { "severityValue":4, "thresholdValue":40, "severityColorLight":"#FEE6C1", "severityColor":"#FCB64E", "severityLabel":"medium" }, { "severityValue":3, "thresholdValue":60, "severityColorLight":"#FFF4C5", "severityColor":"#FFE98C", "severityLabel":"low" }, { "severityValue":2, "thresholdValue":80, "severityColorLight":"#DCEFD7", "severityColor":"#99D18B", "severityLabel":"normal" } ], "baseSeverityLabel":"normal", "isMaxStatic":false }, "adaptive_thresholding_training_window":"-7d", "gap_severity_color":"#CCCCCC", "search_alert_earliest":"15", "alert_lag":"30", "time_variate_thresholds":false, "is_entity_breakdown":false, "entity_alias_filtering_fields":null, "anomaly_detection_training_window":"-7d", "type":"service_health", "time_variate_thresholds_specification":{ "policies":{ "default_policy":{ "title":"Default", "aggregate_thresholds":{ "isMinStatic":true, "gaugeMax":100, "metricField":"count", "renderBoundaryMin":0, "baseSeverityValue":1, "renderBoundaryMax":100, "baseSeverityColor":"#AED3E5", "search":"", "baseSeverityColorLight":"#E3F0F6", "thresholdLevels":[ ], "gaugeMin":0, "isMaxStatic":false, "baseSeverityLabel":"info" }, "entity_thresholds":{ "isMinStatic":true, "gaugeMax":100, "metricField":"count", "renderBoundaryMin":0, "baseSeverityValue":1, "renderBoundaryMax":100, "baseSeverityColor":"#AED3E5", "search":"", "baseSeverityColorLight":"#E3F0F6", "thresholdLevels":[ ], "gaugeMin":0, "isMaxStatic":false, "baseSeverityLabel":"info" }, "policy_type":"static" } }, "time_blocks":[ { "policy_key":"default_policy", "time_block_key":"00-00" }, { "policy_key":"default_policy", "time_block_key":"00-01" }, { "policy_key":"default_policy", "time_block_key":"00-02" }, { "policy_key":"default_policy", "time_block_key":"00-03" }, … { "policy_key":"default_policy", "time_block_key":"05-10" }
itoa_interface/get_alias_list
API to get the list of alias field names (identifier and informational) from all ITSI entities.
GET
Get list of alias field names from all ITSI entities.
Request parameters
None.
Data payload
None.
Return
List of alias field names.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/get_alias_list
JSON Response
{ "identifier":[ "web_server", "vm_id", "site", "hypervisor_id", "hypervisor_name", "datastore_id", "host", "datastore_name", "vm_title", "vm_name", "application_server" ], "informational":[ "version_number", "cluster_name", "processor", "family", "mem_capacity_GB", "nic_count", "hyperthreading", "root_url", "storage_free_space_GB", "vendor", "virtual_subnet_id", "vendor_product_runtime", "hypervisor_os_version", "mem_capacity_MB", "root_volume_type", "logical_cpu_count", "datastore", "cluster_id", "vm_os_version", "dest_port", "vm_name", "storage_capacity_GB", "product", "root_path", "power_state", "vm_size", "product_family_abbreviation", "vendor_product", "ip", "dest_ip", "host", "region", "full_host_name", "datacenter", "cpu_cores", "virtual_network_id", "hypervisor_os", "vm_os", "itsi_role", "hypervisor_id", "nic_type", "vendor_product_runtime_version", "hypervisor_name", "version", "type", "datastore_volume_path", "account_id", "processor_socket_count" ] }
itoa_interface/service/<_key>/base_service_template
API to perform bulk link operations from one or more services to a service template. Requires write access to the specific services and read access to Global team.
GET
Get service template identifier for the service template linked to a service.
Request parameters
None.
Data payload
None.
Return
Dict of {'_key': service_template_id}
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/service/5a0084fd-a090-42fa-9283-0bbe5080429c/base_service_template
JSON Response
{ "_key":"00a2f562-19ad-4398-8f12-918bc04a372b" }
POST
Link one or more services to a service template.
When linking a service to a service template via the UI, where entity rules are defined you have the option of appending or replacing template rules, or keeping existing service rules. However, changing the linked service template via REST gives no option on how to handle entity rules, and as a result defaults to appending template rules. If you want to replace or keep existing rules, use the UI instead of REST.
Request parameters
None.
Data payload
Must be a dictionary of valid schema for the object type. See ITSI REST API schema.
Return
Dict of {'_key': service_template_id}
Example request and response
curl -k -u admin:password -X POST -H "Accept: application/json" -H "Content-type: application/json" --data '{"_key": "491b90d8-62f3-4aeb-be9e-6ccb0b7e63b8"}' https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/service/6b0dda59-de86-4b9d-8817-460b5091d28c/base_service_template
JSON Response
{ "_key":"6b0dda59-de86-4b9d-8817-460b5091d28c" }
Event Management Interface
This interface encapsulates operations on the following objects:
- notable_event_group
- notable_event_comment
- notable_event_aggregation_policy
- correlation_search
As of version 4.4.x, episode comments are append only. ITSI no longer supports update and delete operations on the notable_event_comment
object type.
Base URL
https://<splunk server like localhost>:<splunkd port like 8089>/servicesNS/<user>/<app>/event_management_interface
event_management_interface/<object_type>
API to perform bulk CRUD operations on event management objects.
This API does not support bulk GET operations for the notable_event_comment
object type. You can only perform GET operations on individual episode comments.
GET
Get list of event management objects.
Request parameters
Name | Type | Description |
---|---|---|
is_partial_data | Number | 1 indicates the payloads specified for update are partial, 0 and default indicate no. |
sort_key | String | Name of field to sort by. |
sort_dir | Number | 1 for ascending and 0 for descending. |
limit | Number | Maximum number of entries to throttle at. |
skip | Number | Specifies number n where n is the number of entries to skip from the start. Used primarily for paging. |
fields | String | Comma-separated list of field names to select from the results. |
filter_data | String | Mongodb syntax of rules expressions to filter the payload. See How to use the filter parameter. |
Data payload
None.
Return
List of objects queried.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/event_management_interface/notable_event_group/\?limit\=1
JSON Response
[ { "_owner":"nobody", "severity":"1", "owner":"unassigned", "create_time":1497563236.63525, "_key":"000f91af-ac7d-45e2-a498-5c4b6fe96431", "object_type":"notable_event_group", "status":"5", "_user":"nobody", "mod_time":1497563236.63525 } ]
POST
Create new event management objects.
Request parameters
None.
Data payload
Dictionary of valid schema for the object types for POST. POST is considered an upsert. See ITSI REST API schema.
Return
Object identifier for object created.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/event_management_interface/notable_event_group -X POST -H "Content-Type:application/json" -d '{"data":{"status":"1","severity":"4","_key":"004b2eed-4551-481f-9487-9cf96b58e59d"}}'
JSON Response
{ "_key":"004b2eed-4551-481f-9487-9cf96b58e59d" }
DELETE
Delete event management objects.
Request parameters
Name | Type | Description |
---|---|---|
is_partial_data | Number | 1 indicates the payloads specified for update are partial, 0 and default indicate no. |
sort_key | String | Name of field to sort by. |
sort_dir | Number | 1 for ascending and 0 for descending. |
limit | Number | Maximum number of entries to throttle at. |
skip | Number | Specifies number n where n is the number of entries to skip from the start. Used primarily for paging. |
fields | String | Comma separated list of field names to select from the results. |
filter_data | Number | Mongodb syntax of rules expressions to filter the payload. See How to use the filter parameter. |
ids | String | A string formatted list of event (object) IDs where each event ID is a string. Sample: '["foo"]' |
Return
None.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/event_management_interface/notable_event_group/\?filter\='\{"_key":"004b2eed-4551-481f-9487-9cf96b58e59d"\}' -X DELETE
To prevent accidental deletion of good data, make sure to use the correct filter syntax. Incorrect filter syntax will cause all rows to be deleted for the object type. A better method for deletion is to use an object identifier, such as "60d9300f-0942-4bda-bdec-5ad4baf633b6", rather than a filter.
JSON Response
event_management_interface/<object_type>/<object identifier>
API to perform CRUD operations on a single object. The object identifier is the value populated in the _key
field returned in the REST call for upsert.
Closing an episode through this API changes its status to Closed but doesn't break the episode, so it continues to receive events. To break an episode through the API, you must make the following two REST calls:
/servicesNS/nobody/SA-ITOA/event_management_interface/notable_event_group/{episode ID}
/servicesNS/nobody/SA-ITOA/event_management_interface/notable_event_group?break_group_policy_id={aggregation policy ID}
One call changes the status to Closed and one sends a breaking event to the itsi_tracked_alerts index.
GET
Gets an object based on id.
Request parameters
None.
Data Payload
None.
Return
The object queried.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/event_management_interface/notable_event_group/<object identifier>
JSON Response
{ "_owner":"nobody", "severity":"1", "owner":"unassigned", "create_time":1497563236.63525, "_key":"000f91af-ac7d-45e2-a498-5c4b6fe96431", "object_type":"notable_event_group", "status":"5", "_user":"nobody", "mod_time":1497563236.63525 }
POST
Update objects by object id.
Request parameters
Name | Type | Description |
---|---|---|
is_partial_data: | Number | 1 if payload for update is partial payload, 0 or default indicates entire payload for the object schema is provided. 0 or default overwrites the existing object entirely. . |
Return
Object identifier for updated object.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/event_management_interface/notable_event_group/id/?is_partial_data=1 -X POST -H "Content-Type:application/json" -d '{"severity": "6"}'
JSON Response
{ "_key":"dae39a42-d470-11e6-9b30-a0999b0be454" }
event_management_interface/<object_type>/count
GET
Get count of objects of an object type.
Request parameters
Name | Type | Description |
---|---|---|
filter | String | MongoDB syntax of rules expressions to filter the objects. See How to use the filter parameter.
If no filter is specified, "all" is assumed. |
Data payload None.
Return
Count of objects of the object type, that match the filter criteria if provided or get count of all.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/event_management_interface/notable_event_group/count/?filter_data='\{"status":"2"\}'
JSON Response
{ "count":1492 }
event_management_interface/notable_event_actions
API to get a list of configured episode actions.
GET
Get list of configured episode actions.
Request parameters
None.
Data payload None.
Return List of actions configured.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/event_management_interface/notable_event_actions
JSON Response
{ "label":"Remedy Incident Integration", "is_group_compatible":"1", "execute_once_per_group":"1", "action_name":"remedy_incident", "execute_in_sync":"1", "is_bulk_compatible":"1" }, { "label":"Ping host", "is_group_compatible":"1", "execute_once_per_group":"0", "action_name":"itsi_sample_event_action_ping", "execute_in_sync":0, "is_bulk_compatible":"1" }, { "label":"ServiceNow Incident Integration", "is_group_compatible":"1", "execute_once_per_group":"1", "action_name":"snow_incident", "execute_in_sync":"1", "is_bulk_compatible":"1" }, { "label":"Run a script", "is_group_compatible":"1", "execute_once_per_group":0, "action_name":"script", "execute_in_sync":0, "is_bulk_compatible":"1" }, { "label":"Send email", "is_group_compatible":"1", "execute_once_per_group":0, "action_name":"email", "execute_in_sync":0, "is_bulk_compatible":"1" }
event_management_interface/notable_event_actions/<action name>
API to get configuration or execute a configured episode action.
GET
Get configuration of an episode action.
Request parameters
None.
Data payload
None.
Return
Configuration for the action.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/event_management_interface/notable_event_actions/script
JSON Response
{ "ttl":600, "filename":"", "eai:userName":"nobody", "eai:acl":null, "track_alert":true, "maxresults":10000, "description":"Invoke a custom script", "label":"Run a script", "maxtime":"5m", "eai:appName":"SA-ITOA", "disabled":false, "hostname":"", "icon_path":"mod_alert_icon_script.png", "command":"runshellscript \"$action.script.filename$\" \"$results.count$\" \"$search$\" \"$search$\" \"$name$\" \"Saved Search [$name$] $counttype$($results.count$)\" \"$results.url$\" \"$deprecated_arg$\" \"$search_id$\" \"$results.file$\" maxtime=\"$action.script.maxtime{default=5m}$\"" }
POST
Execute a configured episode action.
Request parameters
None.
Data payload
Parameters specific to the action type.
Return
Object identifier for object created.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/event_management_interface/notable_event_actions/script -X POST -H "Content-Type:application/json" -d '{"params": {"filename": "foo"}, "ids": ["id"]}'
JSON Response
[ { "action_name":"script", "ids":[ "id" ], "sid":"1483652397.71556" } ]
event_management_interface/ticketing
API to perform bulk upsert operations to do ticketing for episodes.
POST
Create new objects by object type.
Request parameters
None.
Data payload
Parameters required for ticketing. Mandatory parameters are:
Name | Type | Description |
---|---|---|
ids | String | Episode identifiers as a list of strings that will be linked to the ticket. |
ticket_system | String | String identifying type of ticket system like lira, snow, and so on. |
ticket_id | Number | Identifier for the ticket. |
ticket_url | String | The URL to use for the ticketing interface. |
Return
Object identifier for object created.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/event_management_interface/ticketing -X POST -H "Content-Type:application/json" -d '{"id": "itsi_group_id", "ticket_system" : "some ticketsystem", "ticket_id": "49454", "ticket_url": "http://ticketsystemuri/49454"}'
JSON Response
{ "6ef7a835-d77d-11e6-a03b-a0999b0be41f" }
event_management_interface/ticketing/<notable event object identifier>
API to get/create/update ticketing for an episode.
GET
Get ticketing information for the episode.
Request parameters
None.
Data payload
Parameters required for ticketing. Mandatory parameters are:
Name | Type | Description |
---|---|---|
ids | String | Episode identifiers as a list of strings that will be linked to the ticket. |
ticket_system | String | String identifying type of ticket system like jira, snow, and so on. |
ticket_id | Number | Identifier for the ticket. |
ticket_url | String | The URL to use for the ticketing interface. |
Return
current ticketing linkage information for the episode
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/event_management_interface/ticketing/id
JSON Response
[
{ "ticket_system":"jira", "_user":"nobody", "event_id":"49eddb9e-53e9-11e7-9e86-005056923ff0", "_key":"252a9999-53f6-11e7-a770-acbc32b40b9d", "tickets":[ { "ticket_system":"jira", "ticket_url":"https://jira.com/123", "ticket_id":"123" } ], "object_type":"external_ticket" }
]
POST
Create new ticket for an episode.
Request parameters
None.
Data payload
Parameters required for ticketing. Mandatory parameters are:
Name | Type | Description |
---|---|---|
ids | String | Episode identifiers as a list of strings that will be linked to the ticket. |
ticket_system | String | String identifying type of ticket system like jira, snow, and so on. |
ticket_id | Number | Identifier for the ticket. |
ticket_url | String | The URL to use for the ticketing interface. |
Return
Object identifier for object created.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/event_management_interface/ticketing/id -X POST -H "Content-Type:application/json" -d '{<payload for ticketing>}'
JSON Response
[ "252a9999-53f6-11e7-a770-acbc32b40b9d" ]
event_management_interface/ticketing/<notable event object identifier>/<ticketing system like jira>/<ticket identifier>
API to delete ticketing linkage for an episode to a specific ticket.
DELETE
Delete ticketing linkage for an episode.
Request parameters
None.
Data payload
None.
Return None.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/event_management_interface/ticketing/id/jira/jira_ticket_id -X DELETE
JSON Response
None.
Maintenance Services Interface
This interface encapsulates operations on ITSI maintenance windows. The supported object type is maintenance_calendar.
Base URL
https://<splunk server like localhost>:<splunkd port like 8089>/servicesNS/<user>/<app>/maintenance_services_interface
maintenance_services_interface/get_supported_object_types
API to get the list of supported objects types in the maintenance services interface.
GET
Gets list of objects types.
Request parameters
None.
Data payload
None.
Return
List of object types.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/maintenance_services_interface/get_supported_object_types
JSON Response
[ "maintenance_calendar" ]
maintenance_services_interface/<object_type>
API to perform bulk CRUD operations on objects and single object create.
GET
Get list of objects by object type
Request parameters
Name | Type | Description |
---|---|---|
sort_key | String | Name of field to sort by. |
sort_dir | Number | 1 for ascending and 0 for descending. |
limit | Number | Maximum number of entries to throttle at. |
offset | Number | specifies number n where n is the number of entries to skip from the start. Used primarily for paging. |
fields | String | Comma-separated list of field names to select from the results. |
filter | String | Mongodb syntax of rules expressions to filter the payload. See How to use the filter parameter. |
Data payload
None.
Return
List of objects queried.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/maintenance_services_interface/maintenance_calendar/?limit=20&fields=title
JSON Response
[ { "_version":"3.0.0", "sec_grp_list":[ "default_itsi_security_group" ], "objects":[ { "object_type":"service", "_key":"95c99846-404f-4c92-9923-2a8c8594bff1" } ], "end_time":1474945061, "_key":"57ebfc569266826c1c3258b7", "mod_timestamp":"2016-09-28 10:22:30.085749", "object_type":"maintenance_calendar", "start_time":1474941460, "title":"curl_mw1", "mod_source":"REST", "identifying_name":"curl_mw1", "_user":"nobody" } ]
POST
Create new objects by object type.
Request parameters
None.
Data payload
Dictionary of valid schema for the object type. See ITSI REST API schema.
Return
Object identifier for object created.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/maintenance_services_interface/maintenance_calendar -X POST -H "Content-Type:application/json" -d '{"title":"foo","start_time":0,"end_time":1,"objects":[{"object_type":"entity","_key":"id"}]}'
JSON Response
{ "_key":"57ebfc569266826c1c3258b7" }
DELETE
Delete objects by object type.
Request parameters
Name | Type | Description |
---|---|---|
sort_key | String | Name of field to sort by. |
sort_dir | Number | 1 for ascending and 0 for descending. |
limit | Number | Maximum number of entries to throttle at. |
offset | Number | Specifies number n where n is the number of entries to skip from the start. Used primarily for paging. |
fields | String | Comma-separated list of field names to select from the results. |
filter | Number | Mongodb syntax of rules expressions to filter the payload.See How to use the filter parameter. |
Data payload:
None.
Return
None.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/maintenance_services_interface/maintenance_calendar/\?filter\='\{"title":"maintenance_calendar_title"\}' -X DELETE
To prevent accidental deletion of good data, make sure to use the correct filter syntax. Incorrect filter syntax will cause all rows to be deleted for the object type. A better method for deletion is to use an object identifier, such as "60d9300f-0942-4bda-bdec-5ad4baf633b6", rather than a filter.
JSON Response
None.
maintenance_services_interface/<object_type>/<object identifier>
API to perform CRUD operations on a single ITSI object. The object identifier is the value populated in its _key field which is returned in the REST call in API for create.
GET
Get objects by object identifier.
Request parameters
None.
Data payload
None.
Return
Object queried.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/maintenance_services_interface/maintenance_calendar/<object identifier>/
JSON Response
{ "objects":[ { "object_type":"service", "_key":"09dd51c2-9fc7-4aa4-9f39-da59ac6b6244" }, { "object_type":"service", "_key":"9e830f4c-47e0-409c-b883-aaeec62ae220" } ], "_owner":"nobody", "_user":"nobody", "object_type":"maintenance_calendar", "start_time":1485457133.415, "_key":"586bf4379266822c631aa2ce", "mod_timestamp":"2017-01-05T21:03:54.366131+00:00", "_version":"2.5.0", "title":"Indefinite MW", "identifying_name":"indefinite mw", "end_time":2147414400, "mod_source":"REST" }
POST
Create new object by object id.
Request parameters
None.
Data payload
Dictionary of valid schema for the object type. See ITSI REST API schema.
Return
Object identifier for object created.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/maintenance_services_interface/maintenance_calendar/<object identifier>/?is_partial_data=1 -X POST -H "Content-Type:application/json" -d '{"end_time": 2}'
JSON Response
{ "_key":"<object identifier>" }
DELETE
Delete objects by object type.
Request parameters
None.
Data payload:
None.
Return
None.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/maintenance_services_interface/maintenance_calendar/id -X DELETE
JSON Response
maintenance_services_interface/<object_type>/count
API to get count of objects of an object type.
GET
Get count of objects of an object type.
Request parameters
Name | Type | Description |
---|---|---|
filter | Number | Mongodb syntax of rules expressions to filter the payload. See How to use the filter parameter. |
Data payload
None.
Return
Count of objects of the object type, that match the filter criteria if provided or get count of all.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/maintenance_services_interface/maintenance_calendar/count
JSON Response
{ "count":3 }
Backup Restore Interface
This interface encapsulates operations on ITSI Backup/Restore jobs that perform backup/restore operations on core ITSI objects. The supported object type is: backup_restore.
The default scheduled backup cannot be deleted through a REST API endpoint, using either bulk delete or single object delete operations.
Base URL
https://<splunk server like localhost>:<splunkd port like 8089>/servicesNS/<user>/<app>/backup_restore_interface
backup_restore_interface/<object_type>
API to perform bulk CRUD operations on objects and single object create.
GET
Get list of objects by object type
Request parameters
Name | Type | Description |
---|---|---|
sort_key | String | Name of field to sort by. |
sort_dir | Number | 1 for ascending and 0 for descending. |
limit | Number | Maximum number of entries to throttle at. |
offset | Number | The number of entries to skip from the start. Used primarily for paging. |
fields | String | Comma separated list of field names to select from the results. |
filter | String | Mongodb syntax of rules expressions to filter the payload. See How to use the filter parameter. |
Data payload
None.
Return
List of objects queried.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/backup_restore_interface/backup_restore/?limit=20&fields=title
JSON Response
[ { "end_time":1483468619.08406, "job_type":"Backup", "create_time":"2017-01-03 10:38:20", "_owner":"nobody", "search_head_id":"95AA5138-51C5-4B97-931E-015B994DF970", "rules":[ ], "mod_source":"REST", "_version":"2.5.0", "status":"Completed", "start_time":1483468614.67937, "path":"/usr/local/bamboo/splunk-install/current/var/itsi/backups/53ba7baf-d445-434a-b088-6e2c1fd91f70/backup", "splunk_server":"", "mod_timestamp":"2017-01-03T18:36:59.096707+00:00", "object_type":"backup_restore", "last_queued_time":1483468614.05747, "last_error":"None", "identifying_name":"a bu job", "title":"A BU Job", "_user":"nobody", "_key":"53ba7baf-d445-434a-b088-6e2c1fd91f70" } ]
POST
Create new objects by object type.
Request parameters
None.
Data payload
Dictionary of valid schema for the object type. See ITSI REST API schema.
Return
Object identifier for object created.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/backup_restore_interface/backup_restore -X POST -H "Content-Type:application/json" -d '{"title": "foo", "job_type": "Backup", "status": "Queued"}'
JSON Response
{ "_key":"de0d5222-fbfd-4ce0-b476-a34a181b1e8b" }
DELETE
Delete objects by object type.
Request parameters
Name | Type | Description |
---|---|---|
sort_key | String | Name of field to sort by. |
sort_dir | Number | 1 for ascending and 0 for descending. |
limit | Number | Maximum number of entries to throttle at. |
offset | Number | specifies number n where n is the number of entries to skip from the start. Used primarily for paging. |
fields | String | Comma separated list of field names to select from the results. |
filter | Number | Mongodb syntax of rules expressions to filter the payload. See How to use the filter parameter. |
Data payload:
None.
Return
None.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/backup_restore_interface/backup_restore?fields='title''&'filter='\{"title":"bar"\}' -X DELETE
To prevent accidental deletion of good data, make sure to use the correct filter syntax. Incorrect filter syntax will cause all rows to be deleted for the object type. A better method for deletion is to use an object identifier, such as "60d9300f-0942-4bda-bdec-5ad4baf633b6", rather than a filter.
JSON Response
backup_restore_interface/<object_type>/<object identifier>
API to perform CRUD operations on a single object. The object identifier is the value populated in its _key field which is returned in the REST call in API for create.
GET
Gets list of object ids.
Request parameters
None.
Data Payload
None.
Return
The object queried.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/backup_restore_interface/backup_restore/<object identifier>
JSON Response
{ "identifying_name":"a bu job", "mod_timestamp":"2017-01-03T18:36:59.096707+00:00", "_owner":"nobody", "status":"Completed", "job_type":"Backup", "object_type":"backup_restore", "_user":"nobody", "rules":[ ], "_version":"2.5.0", "_key":"53ba7baf-d445-434a-b088-6e2c1fd91f70", "create_time":"2017-01-03 10:38:20", "mod_source":"REST", "splunk_server":"", "end_time":1483468619.08406, "start_time":1483468614.67937, "search_head_id":"95AA5138-51C5-4B97-931E-015B994DF970", "title":"A BU Job", "path":"/usr/local/bamboo/splunk-install/current/var/itsi/backups/53ba7baf-d445-434a-b088-6e2c1fd91f70/backup", "last_error":"None", "last_queued_time":1483468614.05747 }
POST
Update objects by object id.
Request parameters
Name | Type | Description |
---|---|---|
is_partial_data: | Number | 1 if payload for update is partial payload, 0 or default indicates entire payload for the object schema is provided. 0 or default overwrites the existing object entirely. |
Return
Object identifier for updated object.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/backup_restore_interface/backup_restore/<object identifier>/?is_partial_data=1 -X POST -H "Content-Type:application/json" -d '{"description": "foo"}'
JSON Response
{ "_key":"<object identifier>" }
DELETE
Delete objects by object id.
Request parameters
None.
Data payload None.
Return
None.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/backup_restore_interface/backup_restore/<object identifier> -X DELETE
JSON Response
backup_restore_interface/<object_type>/count
API to get count of objects of an object type.
GET
Get count of objects by object type.
Request parameters
Name | Type | Description |
---|---|---|
filter | Number | Mongodb syntax of rules expressions to filter the objects. See How to use the filter parameter.
If no filter is specified, "all" is assumed. |
Data payload
None.
Return
Count of objects of the object type that match the filter criteria if provided or get count of all.
Example request and response
curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/backup_restore_interface/backup_restore/count
JSON Response
{ "count":1 }
Glass table icon Interface
This interface encapsulates operations on glass table icons in the KV store.
Base URL
https://<splunk server like localhost>:<splunkd port like 8089>/services/SA-ITOA/v1/icon_collection
services/SA-ITOA/v1/icon_collection
API to perform CRUD operations for glass table icons in the KV store.
GET
Returns a list of icons in the KV store icon library.
Request parameters
Name | Type | Description |
---|---|---|
sort_key | String | Name of field to sort by. |
sort_dir | Number | 1 for ascending and 0 for descending. |
limit | Number | Maximum number of entries to throttle at. |
offset | Number | specifies number n where n is the number of entries to skip from the start. Used primarily for paging. |
fields | String | Comma separated list of field names to select from the results. |
filter | String | Mongodb syntax of rules expressions to filter the payload. See How to use the filter parameter. |
list_categories | Number | If set to 1, returns the full list of categories found among the icons. |
category | String | When set, only returns icons under specified category. |
Data payload
None.
Return
List of objects queried.
If list_categories =1, returns a list. Each list element is a JSON object containing:
- name - title of the category
- immutable - when present, the category can't be modified. Immutable categories are made up of icons imported from .conf files with an automated script in ITSI. They are not allowed to be modified in order to prevent the KV store from becoming out of sync with the configuration files.
Example request and response
curl -k -u admin:password https://localhost:8089/services/SA-ITOA/v1/icon_collection?fields=title,_key
JSON Response
{ "total":47, "result":[ { "_key":"5a9eb1e07bc52f76a2326e41", "title":"500pxa" }, { "_key":"5a9eb1e07bc52f76a2326e44", "title":"Active Directory" }, ... ] }
Example request and response
curl -k -u admin:changeme https://localhost:8089/services/SA-ITOA/v1/icon_collection?list_categories=1
JSON Response
Formatted JSON Data [ { "immutable":1, "name":"Application" }, { "immutable":1, "name":"General" }, { "immutable":1, "name":"Network" }, { "immutable":1, "name":"Random" }, { "immutable":1, "name":"Splunk" }, { "immutable":1, "name":"a123" }, { "immutable":1, "name":"a23" }, { "immutable":1, "name":"aa1" }, { "immutable":1, "name":"asd2" }, { "immutable":0, "name":"asd3" }, { "immutable":1, "name":"sdfsd" } ]
PUT
Creates or updates multiple icons in one batch.
Request parameters
None.
Data payload
List of JSON objects with icon data to be saved.
Keys:
- title
- svg_path
- default_width
- default_height
- category
See ITSI REST API schema for dictionary of valid schema for the object type.
Return
list of objects (_key) saved in KV store.
Example request and response
curl -k -u admin:password https://localhost:8089/services/SA-ITOA/v1/icon_collection -X PUT --data-binary '[{"svg_path":"M341.333 859q0 31 21.5 52t51.5 21h37v165q0 23 16 39t38.5 16 39-16 16.5-39V932h74v165q0 23 16 39t39 16 39-16 16-39V932h35q31 0 52-21.5t21-51.5V493h-512v366zm-110-399q-30 0-51.5 21.5t-21.5 51.5v253q0 30 21.5 51.5t51.5 21.5 51.5-21.5 21.5-51.5V533q0-30-21.5-51.5t-51.5-21.5zm506-250l38-64q6-10-4-16-9-6-15 4l-41 66q-50-18-117-18-68 0-118 19l-41-67q-6-10-15.5-4t-3.5 16l39 64q-118 58-118 226v15h512v-15q0-170-116-226zm-258 136q-12 0-20-8.5t-8-20.5 8-20 20-8 20.5 8 8.5 20-8.5 20.5-20.5 8.5zm237 0q-12 0-20.5-8.5t-8.5-20.5 8.5-20 20.5-8 20.5 8 8.5 20-8.5 20.5-20.5 8.5zm247 114q-30 0-51.5 21.5t-21.5 51.5v253q0 30 21.5 51.5t51.5 21.5 51.5-21.5 21.5-51.5V533q0-30-21.5-51.5t-51.5-21.5z","default_width":1036.3330078125,"title":"android","default_height":1152,"category":"asd3"}]'
JSON Response
[ "5afc83237bc52f686e5023c1" ]
DELETE
Delete icons in the KV store icon library.
Request parameters
Name | Type | Description |
---|---|---|
category | String | When set, deletes all icons in that category. |
Data payload:
None.
Return
Success message.
Example request and response
To delete all icons from KV store:
curl -k -u admin:password https://localhost:8089/services/SA-ITOA/v1/icon_collection?category=* -X DELETE
JSON Response
{ "Deleted":"True" }
services/SA-ITOA/v1/icon_collection/<object identifier>
Delete a glass table icon. The object identifier is the _key field value for the icon.
DELETE
Deletes the icon provided in the _key.
Request parameters
None.
Data payload:
None.
Return
Success message.
Example request and response
curl -k -u admin:password https://localhost:8089/services/SA-ITOA/v1/icon_collection/5a9eb1e07bc52f76a2326e41 -X DELETE
JSON Response
{ "Deleted":"True" }
NEXT ITSI REST API schema |
This documentation applies to the following versions of Splunk® IT Service Intelligence: 4.4.0, 4.4.1, 4.4.2
Feedback submitted, thanks!