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> is nobody and <app> is SA-ITOA.
• splunkd core settings for compression, payload limits, and so on in web.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"
}