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 Splunk IT Service Intelligence (ITSI) REST API endpoints exposed via the splunkd management port 8089. You can use this API to interact programmatically and extend the functionality of 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 the web.conf file apply to endpoints.

How to use the filter parameter

The ITSI REST API uses the MongoDB syntax of rules expressions to filter the payload. The filter has to be valid JSON. When using cURL, the filter JSON has to be URL encoded.

Example 1: Use filter to look up an object with title "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.

Example 3: URL encode filter JSON.

curl --location -g --request GET 'https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/entity?fields='title,_key'&filter={%22entity_type%22:%22API%22}' -k -u admin

How to use the rest command for SA-ITOA endpoints

You can use the Splunk rest command, see rest command to perform REST operations within Splunk Web. Remove the curl command from the request body to form a search similar to the following:

| rest splunk_server=local /servicesNS/nobody/SA-ITOA/event_management_interface/correlation_search report_as=text

The rest command has some arguments that differ from those accepted by REST API endpoints. For example, the limit argument for endpoints is replaced by the count argument, so \?limit\=1 is replaced by count=1

As of ITSI 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 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	Perform operations on core ITSI objects such as entities, services, service templates, and deep dives.
Event Management Interface	Perform operations on ITSI event management objects such as episodes, aggregation policies, and correlation searches.
Maintenance Services Interface	Perform operations on ITSI maintenance windows.
Backup Restore Interface	Perform operations on ITSI backup and restore jobs.
Glass table icon interface	Perform operations on ITSI glass table icons stored in the KV store.

ITSI object data structures

For detailed information about 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
• kpi_template
• kpi_threshold_template
• event_management_state
• entity_filter_rule
• entity_type
• custom_threshold_windows

Base URL

https://<splunk server like localhost>:<splunkd port like 8089>/servicesNS/<user>/<app>/itoa_interface

itoa_interface/get_alias_list

GET

Get a list of alias field names from all ITSI entities in your environment.

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",
      "account_id",
      "processor_socket_count"
   ]
}

itoa_interface/get_supported_object_types

Get a list of supported object types in the ITOA interface.

GET

Get a list of supported object types.

Request parameters
None.

Data payload
None.

Return
List of object types supported within the ITOA interface.

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",
   "entity_type"
]

Note: The entity_relationship and entity_relationship_rule objects are not used.

itoa_interface/<object_type>

Perform CRUD operations on ITSI objects and create individual objects.

GET

Get a list of objects in your environment by object type.

Request parameters

Name	Type	Description
sort_key	String	Name of the field to sort by.
sort_dir	Integer	How to sort the results. 1 for ascending and 0 for descending.
limit	Integer	The maximum number of entries to return. If limit isn't set, all entries are returned.
offset	Integer	The number of entries to skip from the start. Used primarily for paging.
fields	String	A 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 causes 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 and update new objects by object type.

Request parameters
None.

Data payload:
A dictionary of valid schema for the object type. See ITSI REST API schema.

Return
The key of the object created or updated.

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 in your environment by object type.

Request parameters

Name	Type	Description
sort_key	String	Name of the field to sort by.
sort_dir	Integer	How to sort the results. 1 for ascending and 0 for descending.
limit	Integer	The maximum number of entries to return. If limit isn't set, all entries are returned.
offset	Integer	The number of entries to skip from the start. Used primarily for paging.
fields	String	A 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.

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 causes all rows to be deleted for the object type. A better method for deletion is to use an object's key, such as "60d9300f-0942-4bda-bdec-5ad4baf633b6", rather than a filter.

JSON Response
None

itoa_interface/<object_type>/bulk_update

Bulk create and update ITOA interface objects such as entities, services, and KPI base searches. The key is the value populated in the _key field which is returned in the REST call in the API for create. For example: "_key" : "60d9300f-0942-4bda-bdec-5ad4baf633b6".

POST

Update multiple objects of a particular type.

Request parameters

Name	Type	Description
is_partial_data	Boolean	1 if the payload for the update is a partial payload. 0 indicates the entire payload for the object schema provided and overwrites the existing object. Default is 0.

Data payload
A dictionary of valid schema for the object type. See the ITSI REST API schema.

Return
The unique key value for the 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": "object-1", "description": "foo"}]'

JSON Response

{  
   "_key":"object-1"
}

itoa_interface/<object_type>/<_key>

Perform CRUD operations on a single ITSI object. The key is the value populated in the _key field which is returned in the REST call in the API for create. For example: "_key" : "60d9300f-0942-4bda-bdec-5ad4baf633b6".

GET

Get information about a specific ITSI object.

Request parameters
None.

Data payload
None.

Return
A list of objects queried.

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 the field values of a specific object.

Request parameters

Name	Type	Description
is_partial_data	Boolean	1 if the payload for the update is a partial payload. 0 indicates the entire payload for the object schema provided and overwrites the existing object. Default is 0.

Data payload
A dictionary of valid schema for the object type. See ITSI REST API schema.

Return
The key of the updated object.

Example request and response

curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/entity/<_key>/?is_partial_data=1 -X POST -H "Content-Type:application/json" -d '{"description": "foo"}' 

JSON Response

{  
   "_key":"8b12efff-d81d-409e-8607-35d504e7b4a1"
}

DELETE

Delete an object.

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

Get a count of objects of a particular type in your environment.

GET

Get a count of objects of a particular 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
A count of objects of the object type that match the filter criteria, if provided. If you don't provide any filtering criteria, the request returns a count of all objects in your environment.

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>/<_key>/templatize

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.

The key is the value populated in the _key field which is returned in the REST call in the API for create. For example: "_key" : "60d9300f-0942-4bda-bdec-5ad4baf633b6".

GET

Get the template of an 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/<_key>/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/service/<_key>/base_service_template

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 the key value for the service template linked to a service.

Request parameters
None.

Data payload
None.

Return
Dictionary 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 the rules in the template or keeping the existing rules. However, changing the linked service template via REST gives no option to handle entity rules. As a result, the request defaults to appending template rules. If you want to replace or keep the existing rules, edit the template through the UI instead of the API.

Request parameters
None.

Data payload
A dictionary of valid schema for the object type. See ITSI REST API schema.

Return
Dictionary 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"
}

itoa_interface/content_pack

API to get a list of available content packs in the ITSI Content Library. Use the installed_versions key to determine whether a content pack is currently installed on your system. For more information about the Content Library, see About the ITSI Content Library.

GET

Retrieves a list of content packs in the Content Library.

Request parameters

Name	Type	Description
count	Integer	The maximum number of entries to return. If count isn't set, all entries are returned.
offset	Integer	Index of the first item to return.
sort_dir	String	The response sort order: asc = ascending order desc = descending order
sort_key	String	The field name to use for sorting.

Data payload
None.

Return
An array with success and failure keys. The success key contain an array with information about each content pack. The failure key contains an array with error information about each content pack that failed to load.

Example request

curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/content_pack?count=2&sort_key=name

JSON Response

https://docs.splunk.com/Documentation/ITSI/4.11.3/RESTAPI/ITSIRESTAPIreference

itoa_interface/content_pack/<name>/<version>

API to retrieve information about a single content pack in the ITSI Content Library.

GET

Gets information about a content pack.

Request parameters
None.

Data payload
None.

Return
A dictionary of keys representing information about the requested content pack.

Example request

curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/content_pack/CP-ITSI-GT/1

JSON Response

{
   "author":"",
   "description":"The ITSI Content Pack for Example Glass…",
   "icon":"app/CP-ITSI/CP-ITSI-GT/icon.png",
   "id":"CP-ITSI-GT",
   "help_links":[
   ],
   "title":"Example Glass Tables",
   "version":"1",
   "installed_versions":[
   ],
   "screenshots":[
    {
        "path":"app/CP-ITSI/CP-ITSI-GT/screenshots/placeholder2.png",
        "thumb":"app/CP-ITSI/CP-ITSI-GT/screenshots/placeholder2_thumb.png"
    }
   ],
   "main_screenshot":{
 
    "path":"app/CP-ITSI/CP-ITSI-GT/screenshots/CP-ITSI-GT.png",
    "thumb":"app/CP-ITSI/CP-ITSI-GT/screenshots/CP-ITSI-GT.png"
   },
   "overview":"The IT Service Intelligence (ITSI) Content Pack for Example Glass Tables provides a starting point for…"
}

itoa_interface/content_pack/<name>/<version>/install

API to install a content pack from the ITSI Content Library.

POST

Installs the content pack with a specified ID and version in your environment.

Request parameters

Name	Type	Description
content	Array	Optional. Selectively install objects from the content pack. If you include one or more object IDs, only those objects are installed. If no ID is passed, all objects in the content pack are installed.
resolution	String	Optional. Determine whether to append or replace objects. overwrite - Overwrites any existing matching objects previously installed from the content pack. Any changes you previously made to the content pack objects from a prior installation are overwritten. skip - Only installs content pack objects not already installed in your environment.
enabled	Boolean	Optional. Install services, correlation searches, or notable event aggregation policies as enabled. Objects such as saved searches and base searches are still installed in their original state. Set this to enabled=1 in order to install objects as enabled. If you don't set the enabled parameter, objects are installed as disabled.
prefix	String	Optional. Add a prefix to each object installed from the content pack. Defaults to an empty string if not provided.
backfill	Boolean	Optional. Backfills your ITSI environment with the previous seven days of KPI data. Does not apply to service health scores. Default is true.

Data payload
A dictionary of valid schema.

Return
A dictionary in the format {success: [], failure: []} , where the list of items contains the title and either the ID of what was successfully installed or the key, title, and reason of what failed to install by object_type.

Example request

curl -X POST -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/content_pack/CP-ITSI-GT/1/install -H "Content-Type: application/json" -X POST -d '{"resolution":"skip","prefix":"CP","content":{"glass_tables":["2-transaction-flow","3-online-checkout-funnel","4-data-center-overview","5-airport-operations-status","6-boston-marathon"]}}'

JSON Response

{
   "success":[
      {
         "glass_tables":[
            {
               "id":"3-online-checkout-funnel",
               "title":"CP-3 - Online Checkout Funnel"
            },
            {
               "id":"4-data-center-overview",
               "title":"CP-4 - Data Center Overview"
            },
            {
               "id":"5-airport-operations-status",
               "title":"CP-5 - Airport Operations Status"
            },
            {
               "id":"6-boston-marathon",
               "title":"CP-6 - Boston Marathon"
            }
         ]
      }
   ],
   "failure":[
      {
         "content_type":"glass_tables",
         "id":"2-transaction-flow",
         "title":"CP-2 - Transaction Flow",
         "type":"OBJECT_ALREADY_EXISTS"
      }
   ]
}

itoa_interface/content_pack/<name>/<version>/preview

API to preview a content pack from the ITSI Content Library.

GET

Preview the title and description of the objects within a single content pack.

Request parameters
None.

Data payload
None.

Return
An array of dictionaries representing each ITSI object type within the content pack. Each dictionary can include the keys id, title, description, and installed.

Example request

curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/content_pack/CP-ITSI-GT/1/preview

JSON Response

{
   "glass_tables":[
      {
         "id":"1-operational-and-executive-visibility",
         "title":"1 - Operational and Executive Visibility",
         "description":"Glass table for operational and executive visibility",
         "installed":false
      },
      {
         "id":"2-transaction-flow",
         "title":"2 - Transaction Flow",
         "installed":true
      },
      {
         "id":"3-online-checkout-funnel",
         "title":"3 - Online Checkout Funnel",
         "installed":false
      },
      {
         "id":"4-data-center-overview",
         "title":"4 - Data Center Overview",
         "installed":false
      },
      {
         "id":"5-airport-operations-status",
         "title":"5 - Airport Operations Status",
         "installed":true
      },
      {
         "id":"6-boston-marathon",
         "title":"6 - Boston Marathon",
         "installed":false
      }
   ]
}

itoa_interface/content_pack/refresh

Syncs itsi_content_packs.conf with locally installed content packs.

POST

Syncs locally installed content packs.

Request parameters
None.

Data payload
List of apps that were added and removed from itsi_content_packs.conf.

Return
None.

Example request

curl -k -u admin:password -X POST https://localhost:8089/servicesNS/nobody/itsi/itoa_interface/content_pack/refresh

JSON Response

{{
   "success":{
      "apps_added":[
         "DA-ITSI-CP-CUST-example_add"
      ],
      "apps_removed":[
         
      ]
   },
   "failed":{
      "apps_added":[
         
      ],
      "apps_removed":[
         
      ]
   }
}
}

itoa_interface/custom_threshold_windows/<object ID>/associate_service_kpi

API to link services and KPIs to a Custom threshold window object using the specific Custom threshold window ID.

POST

Displays list of the Custom threshold windows linked to services to KPIs.

Request parameters

Name	Type	Description
ctw_id	String	The Custom threshold window ID.

Data payload
The key(s) for the Custom threshold window(s).

Return
The key(s) of the Custom threshold window(s) that linked successfully to the specified services or KPIs.

Example request

curl -k -u admin:password https://localhost.com:8089/servicesNS/nobody/SA-ITOA/itoa_interface/custom_threshold_windows/{ctw_id}/associate_service_kpi

JSON Response

{
  "services": [
    {
      "_key": "c0f4e52a-fcc2-43fd-af32-6a6e36245d11",
      "kpi_ids": [
        "91234523-f480-438a-84e7-87a35d438910",
        "55556523-f480-438a-84e7-87a35d412345"
      ]
    }
  ]
}

itoa_interface/custom_threshold_windows/<object ID>/disconnect_kpis

API to un-link services and KPIs from a Custom threshold windows object.

POST

Displays a list of Custom threshold windows un-linked from services and KPIs.

Request parameters

Name	Type	Description
ctw_id	String	The Custom threshold window ID.

Data payload
None.

Return
The key(s) of the Custom threshold window that was successfully un-linked from the services and KPIs in the request.

Example request

curl -k -u admin:password https://localhost.com:8089/servicesNS/nobody/SA-ITOA/itoa_interface/custom_threshold_windows/{ctw_id}/disconnect_kpis

JSON Response

{
    "service_kpis_dict": [
        {
            "service_id": "df9384a8-4d6b-4868-8c1f-6caaa784f7b1",
            "linked_kpi_ids": [
                "c24fa517cfe14254c3173739",
                "a895284b5e164d32516fbd20"
            ]
        }
    ]
}

itoa_interface/custom_threshold_windows/linked_kpis

API to return the KPIs linked to a specific Custom threshold window ID.

GET

Displays a list of KPIs linked to a specific Custom threshold window.

Request parameters

Name	Type	Description
ctw_id	String	The Custom threshold window ID.
limit	Integer	The maximum number of entries to return. 0 will return all results.

Data payload
The title(s) and key(s) for the linked KPIs or services.

Return
Returns a dictionary/JSON with 2 parameters:

• Linked KPIs: a dictionary of objects that contain kpi_key, kpi_title, service_title, and service_key
• Count: the number of KPIs in the response

Example request

curl -k -u admin:password https://localhost.com:8089/servicesNS/nobody/SA-ITOA/itoa_interface/custom_threshold_windows/linked_kpis/?custom_threshold_window_id=6233c06cdfc63f69cc61aa34&limit=4'

JSON Response

{
   "linked_kpis":[
      {
         "kpi_key":"632fa0c67da8e736f747490d",
         "kpi_title":"0 - test service KPI 1",
         "service_title":"0 - test service",
         "service_key":"342de3d8-0008-4ac5-8929-645d295093a0"
      }
   ],
   "count":1
}

itoa_interface/custom_threshold_windows/${object_ID}/stop

Updates the custom threshold window's status from an Active to Stopped.

POST

Stops the custom threshold window object.

Request parameters
None.

Data payload
None.

Return
The custom threshold window object.

Example request

curl -k -u admin:changeme https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/custom_threshold_windows/92101b7a-816d-445d-8fa2-f0618704af74/stop -X POST

JSON Response

{
    "start_time": 1661985419,
    "cron_schedule": "",
    "recurrence": false,
    "object_type": "custom_threshold_windows",
    "status": "stopped",
    "next_scheduled_time": "",
    "end_time": 1662071819,
    "sec_grp_list": [
        "default_itsi_security_group"
    ],
    "last_stopped_time": 1661989152,
    "mod_source": "unknown",
    "title": "nonrecurring2",
    "description": "",
    "duration": 24,
    "linked_services": [
        {
            "linked_kpi_ids": [
                "cd8bc6bc8ffc1c1eabc0adc0"
            ],
            "service_id": "e3871bfe-dd65-466c-b873-24ab5ea654ab"
        }
    ],
    "mod_timestamp": "2022-08-31T23:39:12.971953+00:00",
    "_version": "4.15.0",
    "identifying_name": "nonrecurring2",
    "pause_description": "",
    "window_type": "percentage",
    "window_config_percentage": 10,
    "window_config_static": {},
    "is_overlapping": false,
    "overlapping_kpis": [],
    "_user": "nobody",
    "_key": "92101b7a-816d-445d-8fa2-f0618704af74",
    "can_view": true,
    "can_link": false,
    "can_edit": false,
    "can_transition": false,
}

itoa_interface/entity/retire

Retires entities based on the entity keys that you pass in.

POST

Retires selected entities. Retired entities are un-linked from associated services.

Request parameters
None.

Data payload
A dictionary that contains an entity object where the value is a list of entity key objects.

Return
The key(s) of the retired entities.

Example request

curl -k -u admin:changeme https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/entity/retire -H "Content-Type: application/json" -X POST -d ' {"data": ["794f8938-9780-4d1b-bf65-572f17312500", "6bacec4f-d69c-4b58-98ba-5c5eaeb22d04"]}

JSON Response

["006ce5d3-be8b-4507-a6eb-67fefe0ebba0", "0d0c7949-9722-4226-bfaf-66f8fb398349", "0d53e99e-5d62-46b9-9949-80118ffd7204", "0da0a715-4d00-45dc-a2e6-fa9026eeecd8", "1248d0c7-baec-4e45-b200-d940b1803231", …. ] 

itoa_interface/entity/restore

Restores retired entities. Any retired entities become active and re-associated with services in the environment.

POST

Restore entities that were retired and re-link retired entities to any associated services.

Request parameters
None.

Data payload
A dictionary that contains an entity object where the value is a list of entity key objects.

Return
The key(s) of the updated entity.

Example request

curl -k -u admin:changeme https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/entity/retire -H "Content-Type: application/json" -X POST -d ' {"data": ["794f8938-9780-4d1b-bf65-572f17312500", "6bacec4f-d69c-4b58-98ba-5c5eaeb22d04"]}

JSON Response

{  
   "_key":"794f8938-9780-4d1b-bf65-572f17312500"
}

itoa_interface/entity/count_retirable

Returns a list of Entities that are flagged for retirement.

GET

Displays a list of all entities marked as ready for retirement.

Request parameters
None.

Data payload
A dictionary that contains an entity object where the value is a list of entity key objects.

Return
A dictionary that contains a list of entity key objects.

Example request

curl -k -u admin:changeme https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/entity/count_retirable

JSON Response

[
    {
        "object_type": "entity",
        "title": "old_entity_37",
        "retirable": 1,
        "sec_grp": "default_itsi_security_group",
        "_key": "006ce5d3-be8b-4507-a6eb-67fefe0ebba0",
        "permissions": {
            "user": "admin",
            "group": {
                "read": true,
                "write": true,
                "delete": true
            },
            "read": true,
            "write": true,
            "delete": true
        }
    },
    {
        "object_type": "entity",
        "title": "old_entity_102",
        "retirable": 1,
        "sec_grp": "default_itsi_security_group",
        "_key": "0d0c7949-9722-4226-bfaf-66f8fb398349",
        "permissions": {
            "user": "admin",
            "group": {
                "read": true,
                "write": true,
                "delete": true
            },
            "read": true,
            "write": true,
            "delete": true
        }
    },
    {
        "object_type": "entity",
        "title": "old_entity_79",
        "retirable": 1,
        "sec_grp": "default_itsi_security_group",
        "_key": "0d53e99e-5d62-46b9-9949-80118ffd7204",
        "permissions": {
            "user": "admin",
            "group": {
                "read": true,
                "write": true,
                "delete": true
            },
            "read": true,
            "write": true,
            "delete": true
        }
    },
]

itoa_interface/entity/retire_retirable

Retires all entities that are marked for retirement. There is no way to cancel a "retire all" action once it is started.

POST

Displays a list of entities that were retired.

Request parameters
None.

Data payload
The key(s) of the entities.

Return
The key(s) of the updated entity.

Example request

curl -k -u admin:changeme https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/entity/retire_retirable -X POST

JSON Response

["006ce5d3-be8b-4507-a6eb-67fefe0ebba0", "0d0c7949-9722-4226-bfaf-66f8fb398349", "0d53e99e-5d62-46b9-9949-80118ffd7204", "0da0a715-4d00-45dc-a2e6-fa9026eeecd8", "1248d0c7-baec-4e45-b200-d940b1803231", …. ] 

Event Management Interface

This interface encapsulates operations on the following ITSI event management objects:

• event_management_state
• notable_event_group
• notable_event_comment
• notable_event_aggregation_policy
• notable_event_email_template
• 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.

GET

Get list of event management objects.

Request parameters

Name	Type	Description
is_partial_data	Boolean	1 if the payload is a partial payload. 0 indicates the entire payload for the object schema is provided and overwrites the existing object. Default is 0.
sort_key	String	Name of field to sort by.
sort_dir	Integer	How to sort the results. 1 for ascending and 0 for descending.
limit	Integer	The maximum number of entries to return. If limit isn't set, all entries are returned.
skip	Integer	The number of entries to skip from the start. Used primarily for paging.
fields	String	A 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
The key of the 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	Boolean	1 if the payload is a partial payload. 0 indicates the entire payload for the object schema is provided and overwrites the existing object. Default is 0.
sort_key	String	Name of field to sort by.
sort_dir	Integer	How to sort the results. 1 for ascending and 0 for descending.
limit	Integer	The maximum number of entries to return. If limit isn't set, all entries are returned.
skip	Integer	The number of entries to skip from the start. Used primarily for paging.
fields	String	A 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.
ids	String	A formatted list of event (object) IDs where each 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 a key, such as "60d9300f-0942-4bda-bdec-5ad4baf633b6", rather than a filter.

JSON Response

event_management_interface/<object_type>/<_key>

API to perform CRUD operations on a single object. The key is the value populated in the _key field returned in the REST call for upsert.

Note: Closing an episode through the 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 two REST calls. For instructions, see Modify episode fields through the REST API in the Event Analytics manual.

GET

Get information about an event management object such as an episode or an aggregation policy.

Request parameters
None.

Data Payload
None.

Return
A JSON object of key-value pairs describing 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/<_key>

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 specific fields within an event management object.

Request parameters

Name	Type	Description
is_partial_data	Boolean	1 if the payload is a partial payload. 0 indicates the entire payload for the object schema is provided and overwrites the existing object. Default is 0.

Return
The key of the 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

API to get a count of event management objects of a specific type. For example, you could retrieve a count of aggregation policies or correlation searches in your environment.

GET

Get a count of objects of a specific 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. Otherwise returns a count of all objects of that type.

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 available episode actions, such as running a script or sending an email.

GET

Get list of available 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",
      "type":"external_ticket",
      "is_group_compatible":0,
      "action_name":"remedy_incident",
      "execute_once_per_group":0,
      "execute_in_sync":"1",
      "is_bulk_compatible":"0"
   },
   { 
      "label":"Link Ticket",
      "type":"",
      "is_group_compatible":0,
      "action_name":"itsi_event_action_link_ticket",
      "execute_once_per_group":0,
      "execute_in_sync":"1",
      "is_bulk_compatible":"1"
   },
   { 
      "label":"Add reference link",
      "type":"",
      "is_group_compatible":0,
      "action_name":"itsi_event_action_link_url",
      "execute_once_per_group":0,
      "execute_in_sync":"1",
      "is_bulk_compatible":"1"
   },
   { 
      "label":"Send email",
      "type":"",
      "is_group_compatible":0,
      "action_name":"email",
      "execute_once_per_group":0,
      "execute_in_sync":0,
      "is_bulk_compatible":"0"
   },
   { 
      "label":"Send to Phantom",
      "type":"",
      "is_group_compatible":0,
      "action_name":"itsi_event_action_send_to_phantom",
      "execute_once_per_group":0,
      "execute_in_sync":0,
      "is_bulk_compatible":"0"
   },
   { 
      "label":"Ping host",
      "type":"",
      "is_group_compatible":0,
      "action_name":"itsi_sample_event_action_ping",
      "execute_once_per_group":"0",
      "execute_in_sync":0,
      "is_bulk_compatible":"0"
   },
   { 
      "label":"ServiceNow Incident Integration",
      "type":"external_ticket",
      "is_group_compatible":0,
      "action_name":"snow_incident",
      "execute_once_per_group":0,
      "execute_in_sync":"1",
      "is_bulk_compatible":"1"
   },
   { 
      "label":"VictorOps",
      "type":"",
      "is_group_compatible":0,
      "action_name":"victorops",
      "execute_once_per_group":0,
      "execute_in_sync":"1",
      "is_bulk_compatible":"0"
   },
   { 
      "label":"Run a script",
      "type":"",
      "is_group_compatible":0,
      "action_name":"script",
      "execute_once_per_group":0,
      "execute_in_sync":0,
      "is_bulk_compatible":"0"
   }
]

event_management_interface/notable_event_actions/<action_name>

API to get information about an episode action or execute a configured episode action. The action name is the action_name field returned in a GET request to the event_management_interface/notable_event_actions endpoint.

GET

Get information about an episode action.

Request parameters
None.

Data payload
None.

Return
Configuration information 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
The name and ID of the executed action.

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 for episode tickets.

POST

Create new objects by object type.

Request parameters
None.

Data payload
The following parameters are required:

Name	Type	Description
id	String	Episode identifiers as a list of strings that will be linked to the ticket.
ticket_system	String	A string identifying the name of the ticketing system. For example, Jira, ServiceNow, or Remedy.
ticket_id	String	The unique identifier of the ticket.
ticket_url	String	The URL of the ticket to link.

Return
The key of the 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" : "ServiceNow", "ticket_id": "49454", "ticket_url": "http://ticketsystemuri/49454"}'

JSON Response

{  
   "6ef7a835-d77d-11e6-a03b-a0999b0be41f"
}

event_management_interface/ticketing/<notable event key>

API to get, create, and update an episode's ticket links.

GET

Get information about tickets linked to an episode.

Request parameters

Name	Type	Description
ids	String	Episode identifiers as a list of strings linked to the ticket.
ticket_system	String	String identifying the ticketing system. For example, Jira, ServiceNow, or Remedy.
ticket_id	String	The unique identifier of the ticket.
ticket_url	String	The URL of the ticket to link.

Return
Updated 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

Link a ticket to an episode.

Request parameters

Name	Type	Description
ids	String	Episode identifiers as a list of strings to link to the ticket.
ticket_system	String	String identifying the type of ticketing system. For example, Jira, ServiceNow, or Remedy.
ticket_id	String	The unique identifier of the ticket to link to the episode.
ticket_url	String	The URL of the ticket to link to the episode.

Return
The unique identifier of the created ticket link.

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/<episode identifier>/<ticketing system>/<ticket identifier>

API to delete ticket links from 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. For more information about maintenance windows and their downstream effects, see Overview of maintenance windows in ITSI in the Administration Manual.

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 supported in the maintenance services interface.

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 maintenance windows and create individual maintenance windows in your environment.

GET

Get a list of maintenance windows in your environment.

Request parameters

Name	Type	Description
sort_key	String	Name of field to sort by.
sort_dir	Integer	How to sort the results. 1 for ascending and 0 for descending.
limit	Integer	The maximum number of entries to return. If limit isn't set, all entries are returned.
offset	Integer	The number of entries to skip from the start. Used primarily for paging.
fields	String	A 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
A list of maintenance windows that currently exist in your environment. You can only see maintenance windows to which you have read access.

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 one or more maintenance windows.

Request parameters
None.

Data payload
Dictionary of valid schema for the maintenance_calendar object type. See Maintenance Calendar in the REST API schema.

Return
The key of the created maintenance window.

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 one or more maintenance windows.

Request parameters

Name	Type	Description
sort_key	String	Name of field to sort by.
sort_dir	Integer	How to sort the results. 1 for ascending and 0 for descending.
limit	Integer	The maximum number of entries to return. If limit isn't set, all entries are returned.
offset	Integer	The number of entries to skip from the start. Used primarily for paging.
fields	String	A 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
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 a _key, such as "60d9300f-0942-4bda-bdec-5ad4baf633b6", rather than a filter.

JSON Response

maintenance_services_interface/<object_type>/<_key>

API to perform CRUD operations on single maintenance windows. The _key is the value returned in the POST or GET request.

GET

Get information about a single maintenance window.

Request parameters
None.

Data payload
None.

Return
Information about the maintenance window, including any services or entities within it, its title, and its start and end time.

Example request and response

curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/maintenance_services_interface/maintenance_calendar/<_key>/

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 a single maintenance window and assign it a unique key.

Request parameters
None.

Data payload
Dictionary of valid schema for the maintenance_calendar object type. See Maintenance Calendar in the REST API schema.

Return
The key of the maintenance window created.

Example request and response

curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/maintenance_services_interface/maintenance_calendar/57ebfc569266826c1c3258b7/?is_partial_data=1 -X POST -H "Content-Type:application/json" -d '{"end_time": 2}' 

JSON Response

{  
   "_key":"60d9300f-0942-4bda-bdec-5ad4baf633b6"
}

DELETE

Delete a single maintenance window by key.

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/57ebfc569266826c1c3258b7 -X DELETE 

JSON Response

maintenance_services_interface/<object_type>/count

API to get a count of maintenance windows in your environment. The count only applies to maintenance windows to which you have read access.

GET

Get a count of maintenance windows in your environment.

Request parameters

Name	Type	Description
filter	String	MongoDB syntax of rules expressions to filter the payload. See How to use the filter parameter.

Data payload
None.

Return
Count of maintenance windows that match the filter criteria. If you don't provide filter criteria, all maintenance windows are counted.

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 and restore jobs. The supported object type is backup_restore. For more information about full and partial backups and restores, see Overview of backing up and restoring ITSI KV store data.

You can't delete the default scheduled backup 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 ITSI backups and restores.

GET

Get list of ITSI backup and restore jobs in your environment.

Request parameters

Name	Type	Description
sort_key	String	Name of field to sort by.
sort_dir	Integer	How to sort the results. 1 for ascending and 0 for descending.
limit	Integer	The maximum number of entries to return. If limit isn't set, all entries are returned.
offset	Integer	The number of entries to skip from the start. Used primarily for paging.
fields	String	A 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
A list of backup and restore jobs that exist in your environment. You can only see jobs to which you have read access.

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 backup and restore jobs.

Request parameters
None.

Data payload
Dictionary of valid schema for the object type. See ITSI REST API schema.

Return
The key of the backup or restore 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 one or more backup or restore jobs.

Request parameters

Name	Type	Description
sort_key	String	Name of field to sort by.
sort_dir	Integer	How to sort the results. 1 for ascending and 0 for descending.
limit	Integer	The maximum number of entries to return. If limit isn't set, all entries are returned.
offset	Integer	The number of entries to skip from the start. Used primarily for paging.
fields	String	A 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
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 data, make sure to use the correct filter syntax. Incorrect filter syntax deletes all instances of the specified object type. A better method for deletion is to use an object's key, such as "60d9300f-0942-4bda-bdec-5ad4baf633b6", rather than a filter.

JSON Response

backup_restore_interface/<object_type>/<_key>

API to perform CRUD operations on a single backup or restore job. The key is the value populated in its _key field returned in a GET or POST call.

GET

Get information about a backup or restore job.

Request parameters
None.

Data Payload
None.

Return
Identifying information for the backup or restore job, including the type of job, the ITSI version it was created on, and date and time it was created.

Example request and response

curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/backup_restore_interface/backup_restore/<_key>

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":"4.7.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 a backup or restore job.

Request parameters

Name	Type	Description
is_partial_data:	Boolean	1 if the payload is a partial payload. 0 indicates the entire payload for the object schema is provided and overwrites the existing object. Default is 0.

Return
The key of the backup or restore job that was updated.

Example request and response

curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/backup_restore_interface/backup_restore/<_key>/?is_partial_data=1 -X POST -H "Content-Type:application/json" -d '{"description": "New description"}' 

JSON Response

{  
   "_key":"<object identifier>"
}

DELETE

Delete a backup or restore job.

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/<_key> -X DELETE 

JSON Response

backup_restore_interface/<object_type>/count

API to get count backup and restore jobs in your ITSI environment. You can only see jobs to which you have write access.

GET

Get a count of backup and restore jobs in your environment.

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 backup and restore jobs that match the filter criteria, if provided. Otherwise returns a count of all jobs.

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	Integer	How to sort the results. 1 for ascending and 0 for descending.
limit	Integer	The maximum number of entries to return. If limit isn't set, all entries are returned.
offset	Integer	The number of entries to skip from the start. Used primarily for paging.
fields	String	A 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	Boolean	If set to 1, returns the full list of categories found among the icons.
category	String	When set, only returns icons under the specified category.

Data payload
None.

Return
List of objects queried. If list_categories = 1, returns a list of JSON objects containing the following elements:

• name - The title of the category
• immutable - When present, the category can't be modified. Immutable categories are made up of icons imported from configuration files with an automated script in ITSI. They're immutable 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":"Splunk"
   },
   {  
      "immutable":1,
      "name":"a123"
   },
   {  
      "immutable":1,
      "name":"sdfsd"
   }
]

POST

Bulk create or update multiple glass table icons.

Request parameters

A list of JSON objects with icon data.

Name	Type	Description
sort_key	String	Name of field to sort by.
sort_dir	Integer	How to sort the results. 1 for ascending and 0 for descending.
title	String	The title of the icon.
svg_path	String	The path to the icon SVG file.
default_width	String	The width of the icon in pixels.
default_height	String	The height of the icon in pixels.
category	String	The category under which to store the icon.

See ITSI REST API schema for a dictionary of valid schema for the object type.

Return
The key of the icon or icons saved in the 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":"<path>","default_width":1036.33,"title":"Android","default_height":1152,"category":"Phone Icons"}]'

JSON Response

[  
   "5afc83237bc52f686e5023c1"
]

DELETE

Delete all glass table icons in the KV store icon library.

Request parameters

Name	Type	Description
category	String	When set, deletes all glass table icons in the specified category.

Data payload:
None.

Return
Success message.

Example request and response
To delete all icons from KV store, run the following command:

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/<_key>

Delete a glass table icon.

DELETE

Deletes the icon provided in the _key field.

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