Splunk® IT Service Intelligence

REST API Reference

Download manual as PDF

Download topic as PDF

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/...
    
  • The API is versioned. To use the latest version, either do not specify a version or specify vLatest after the interface name.
    /servicesNS/<user>/<app>/itoa_interface/vLatest/....
    
  • To specify a version, use the syntax: v<version number>.
    /servicesNS/<user>/<app>/itoa_interface/v3.0.0/...
    
  • 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.
  • In version 2.5.0 and later, all time-specific configuration in the ITSI REST API is based on UTC time standard.

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.

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

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

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 ITSI event_management_state objects:

  • event_management_state
  • notable_event_group
  • notable_event_comment
  • notable_event_aggregation_policy
  • correlation_search

As of ITSI 4.0.0, you can no longer make updates to individual notable events using the notable_event object. Updates are only permitted at the notable event group level.

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

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 the ITSI maintenance services. The supported object type is maintenance_calendar.

Base URL

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

maintenance_services_interface/get_supported_object_types

API to get the list of supported objects types in the maintenance services interface.

GET

Gets list of objects types.

Request parameters
None.

Data payload
None.

Return
List of object types.

Example request and response

curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/maintenance_services_interface/get_supported_object_types

JSON Response

[  
   "maintenance_calendar"
]

maintenance_services_interface/<object_type>

API to perform bulk CRUD operations on objects and single object create.

GET

Get list of objects by object type

Request parameters

Name Type Description
sort_key String Name of field to sort by.
sort_dir Number 1 for ascending and 0 for descending.
limit Number Maximum number of entries to throttle at.
offset Number specifies number n where n is the number of entries to skip from the start. Used primarily for paging.
fields String Comma separated list of field names to select from the results.
filter String Mongodb syntax of rules expressions to filter the payload. See How to use the filter parameter.

Data payload
None.

Return
List of objects queried.

Example request and response

curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/maintenance_services_interface/maintenance_calendar/?limit=20&fields=title

JSON Response

[  
   {  
      "_version":"3.0.0",
      "sec_grp_list":[  
         "default_itsi_security_group"
      ],
      "objects":[  
         {  
            "object_type":"service",
            "_key":"95c99846-404f-4c92-9923-2a8c8594bff1"
         }
      ],
      "end_time":1474945061,
      "_key":"57ebfc569266826c1c3258b7",
      "mod_timestamp":"2016-09-28 10:22:30.085749",
      "object_type":"maintenance_calendar",
      "start_time":1474941460,
      "title":"curl_mw1",
      "mod_source":"REST",
      "identifying_name":"curl_mw1",
      "_user":"nobody"
   }
]

POST

Create new objects by object type.

Request parameters
None.

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

Return
Object identifier for object created.

Example request and response

curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/maintenance_services_interface/maintenance_calendar -X POST -H "Content-Type:application/json" -d '{"title":"foo","start_time":0,"end_time":1,"objects":[{"object_type":"entity","_key":"id"}]}'

JSON Response

{  
   "_key":"57ebfc569266826c1c3258b7"
}

DELETE

Delete objects by object type.

Request parameters

Name Type Description
sort_key String Name of field to sort by.
sort_dir Number 1 for ascending and 0 for descending.
limit Number Maximum number of entries to throttle at.
offset Number specifies number n where n is the number of entries to skip from the start. Used primarily for paging.
fields String Comma separated list of field names to select from the results.
filter Number Mongodb syntax of rules expressions to filter the payload.See How to use the filter parameter.

Data payload:
None.

Return
None.

Example request and response

curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/maintenance_services_interface/maintenance_calendar/\?filter\='\{"title":"maintenance_calendar_title"\}' -X DELETE 

To prevent accidental deletion of good data, make sure to use the correct filter syntax. Incorrect filter syntax will cause all rows to be deleted for the object type. A better method for deletion is to use an object identifier, such as "60d9300f-0942-4bda-bdec-5ad4baf633b6", rather than a filter.

JSON Response
None.


maintenance_services_interface/<object_type>/<object identifier>

API to perform CRUD operations on a single ITSI object. The object identifier is the value populated in its _key field which is returned in the REST call in API for create.

GET

Get objects by object identifier.

Request parameters
None.

Data payload
None.

Return
Object queried.

Example request and response

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

JSON Response

{  
   "objects":[  
      {  
         "object_type":"service",
         "_key":"09dd51c2-9fc7-4aa4-9f39-da59ac6b6244"
      },
      {  
         "object_type":"service",
         "_key":"9e830f4c-47e0-409c-b883-aaeec62ae220"
      }
   ],
   "_owner":"nobody",
   "_user":"nobody",
   "object_type":"maintenance_calendar",
   "start_time":1485457133.415,
   "_key":"586bf4379266822c631aa2ce",
   "mod_timestamp":"2017-01-05T21:03:54.366131+00:00",
   "_version":"2.5.0",
   "title":"Indefinite MW",
   "identifying_name":"indefinite mw",
   "end_time":2147414400,
   "mod_source":"REST"
}

POST

Create new object by object id.

Request parameters
None.

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

Return
Object identifier for object created.

Example request and response

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

JSON Response

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

DELETE

Delete objects by object type.

Request parameters
None.

Data payload:
None.

Return
None.

Example request and response

curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/maintenance_services_interface/maintenance_calendar/id -X DELETE 

JSON Response


maintenance_services_interface/<object_type>/count

API to get count of objects of an object type.

GET

Get count of objects of an object type.

Request parameters

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

Data payload
None.

Return
Count of objects of the object type, that match the filter criteria if provided or get count of all.

Example request and response

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

JSON Response

{  
   "count":3
}

Backup Restore Interface

This interface encapsulates operations on ITSI Backup/Restore jobs that perform backup/restore operations on core ITSI objects. The supported object type is: backup_restore.

The default scheduled backup cannot be deleted through a REST API endpoint, using either bulk delete or single object delete operations.

Base URL

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

backup_restore_interface/<object_type>

API to perform bulk CRUD operations on objects and single object create.

GET

Get list of objects by object type

Request parameters

Name Type Description
sort_key String Name of field to sort by.
sort_dir Number 1 for ascending and 0 for descending.
limit Number Maximum number of entries to throttle at.
offset Number The number of entries to skip from the start. Used primarily for paging.
fields String Comma separated list of field names to select from the results.
filter String Mongodb syntax of rules expressions to filter the payload. See How to use the filter parameter.

Data payload
None.

Return
List of objects queried.

Example request and response

curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/backup_restore_interface/backup_restore/?limit=20&fields=title

JSON Response

[  
   {  
      "end_time":1483468619.08406,
      "job_type":"Backup",
      "create_time":"2017-01-03 10:38:20",
      "_owner":"nobody",
      "search_head_id":"95AA5138-51C5-4B97-931E-015B994DF970",
      "rules":[  

      ],
      "mod_source":"REST",
      "_version":"2.5.0",
      "status":"Completed",
      "start_time":1483468614.67937,
      "path":"/usr/local/bamboo/splunk-install/current/var/itsi/backups/53ba7baf-d445-434a-b088-6e2c1fd91f70/backup",
      "splunk_server":"",
      "mod_timestamp":"2017-01-03T18:36:59.096707+00:00",
      "object_type":"backup_restore",
      "last_queued_time":1483468614.05747,
      "last_error":"None",
      "identifying_name":"a bu job",
      "title":"A BU Job",
      "_user":"nobody",
      "_key":"53ba7baf-d445-434a-b088-6e2c1fd91f70"
   }
]

POST

Create new objects by object type.

Request parameters
None.

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

Return
Object identifier for object created.

Example request and response

curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/backup_restore_interface/backup_restore -X POST -H "Content-Type:application/json" -d '{"title": "foo", "job_type": "Backup", "status": "Queued"}'

JSON Response

{  
   "_key":"de0d5222-fbfd-4ce0-b476-a34a181b1e8b"
}

DELETE

Delete objects by object type.

Request parameters

Name Type Description
sort_key String Name of field to sort by.
sort_dir Number 1 for ascending and 0 for descending.
limit Number Maximum number of entries to throttle at.
offset Number specifies number n where n is the number of entries to skip from the start. Used primarily for paging.
fields String Comma separated list of field names to select from the results.
filter Number Mongodb syntax of rules expressions to filter the payload. See How to use the filter parameter.

Data payload:
None.

Return
None.

Example request and response

curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/backup_restore_interface/backup_restore?fields='title''&'filter='\{"title":"bar"\}' -X DELETE 

To prevent accidental deletion of good data, make sure to use the correct filter syntax. Incorrect filter syntax will cause all rows to be deleted for the object type. A better method for deletion is to use an object identifier, such as "60d9300f-0942-4bda-bdec-5ad4baf633b6", rather than a filter.

JSON Response


backup_restore_interface/<object_type>/<object identifier>

API to perform CRUD operations on a single object. The object identifier is the value populated in its _key field which is returned in the REST call in API for create.

GET

Gets list of object ids.

Request parameters
None.

Data Payload
None.

Return
The object queried.

Example request and response

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

JSON Response

{  
   "identifying_name":"a bu job",
   "mod_timestamp":"2017-01-03T18:36:59.096707+00:00",
   "_owner":"nobody",
   "status":"Completed",
   "job_type":"Backup",
   "object_type":"backup_restore",
   "_user":"nobody",
   "rules":[  

   ],
   "_version":"2.5.0",
   "_key":"53ba7baf-d445-434a-b088-6e2c1fd91f70",
   "create_time":"2017-01-03 10:38:20",
   "mod_source":"REST",
   "splunk_server":"",
   "end_time":1483468619.08406,
   "start_time":1483468614.67937,
   "search_head_id":"95AA5138-51C5-4B97-931E-015B994DF970",
   "title":"A BU Job",
   "path":"/usr/local/bamboo/splunk-install/current/var/itsi/backups/53ba7baf-d445-434a-b088-6e2c1fd91f70/backup",
   "last_error":"None",
   "last_queued_time":1483468614.05747
}

POST

Update objects by object id.

Request parameters

Name Type Description
is_partial_data: Number 1 if payload for update is partial payload, 0 or default indicates entire payload for the object schema is provided.

0 or default overwrites the existing object entirely.

Return
Object identifier for updated object.

Example request and response

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

JSON Response

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

DELETE

Delete objects by object id.

Request parameters
None.

Data payload None.

Return
None.

Example request and response

curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/backup_restore_interface/backup_restore/<object identifier> -X DELETE 

JSON Response


backup_restore_interface/<object_type>/count

API to get count of objects of an object type.

GET

Get count of objects by object type.

Request parameters

Name Type Description
filter Number Mongodb syntax of rules expressions to filter the objects. See How to use the filter parameter.

If no filter is specified, "all" is assumed.

Data payload
None.

Return
Count of objects of the object type that match the filter criteria if provided or get count of all.

Example request and response

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

JSON Response

{  
   "count":1
}

Glass table icon Interface

This interface encapsulates operations on glass table icons in the KV store.

Base URL

https://<splunk server like localhost>:<splunkd port like 8089>/services/SA-ITOA/v1/icon_collection 

services/SA-ITOA/v1/icon_collection

API to perform CRUD operations for glass table icons in the KV store.

GET

Returns a list of icons in the KV store icon library.

Request parameters

Name Type Description
sort_key String Name of field to sort by.
sort_dir Number 1 for ascending and 0 for descending.
limit Number Maximum number of entries to throttle at.
offset Number specifies number n where n is the number of entries to skip from the start. Used primarily for paging.
fields String Comma separated list of field names to select from the results.
filter String Mongodb syntax of rules expressions to filter the payload. See How to use the filter parameter.
list_categories Number If set to 1, returns the full list of categories found among the icons.
category String When set, only returns icons under specified category.

Data payload
None.

Return
List of objects queried.

If list_categories =1, returns a list. Each list element is a JSON object containing:

  • name - title of the category
  • immutable - when present, the category can't be modified. Immutable categories are made up of icons imported from .conf files with an automated script in ITSI. They are not allowed to be modified in order to prevent the KV store from becoming out of sync with the configuration files.

Example request and response

curl -k -u admin:password https://localhost:8089/services/SA-ITOA/v1/icon_collection?fields=title,_key

JSON Response

{  
   "total":47,
   "result":[  
      {  
         "_key":"5a9eb1e07bc52f76a2326e41",
         "title":"500pxa"
      },
      {  
         "_key":"5a9eb1e07bc52f76a2326e44",
         "title":"Active Directory"
      },
      ...
   ]
}

Example request and response

curl -k -u admin:changeme https://localhost:8089/services/SA-ITOA/v1/icon_collection?list_categories=1

JSON Response

Formatted JSON Data
[  
   {  
      "immutable":1,
      "name":"Application"
   },
   {  
      "immutable":1,
      "name":"General"
   },
   {  
      "immutable":1,
      "name":"Network"
   },
   {  
      "immutable":1,
      "name":"Random"
   },
   {  
      "immutable":1,
      "name":"Splunk"
   },
   {  
      "immutable":1,
      "name":"a123"
   },
   {  
      "immutable":1,
      "name":"a23"
   },
   {  
      "immutable":1,
      "name":"aa1"
   },
   {  
      "immutable":1,
      "name":"asd2"
   },
   {  
      "immutable":0,
      "name":"asd3"
   },
   {  
      "immutable":1,
      "name":"sdfsd"
   }
]

PUT

Creates or updates multiple icons in one batch.

Request parameters
None.

Data payload
List of JSON objects with icon data to be saved. Keys:

  • title
  • svg_path
  • default_width
  • default_height
  • category

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

Return
list of objects (_key) saved in KV store.

Example request and response

curl -k -u admin:password https://localhost:8089/services/SA-ITOA/v1/icon_collection -X PUT --data-binary '[{"svg_path":"M341.333 859q0 31 21.5 52t51.5 21h37v165q0 23 16 39t38.5 16 39-16 16.5-39V932h74v165q0 23 16 39t39 16 39-16 16-39V932h35q31 0 52-21.5t21-51.5V493h-512v366zm-110-399q-30 0-51.5 21.5t-21.5 51.5v253q0 30 21.5 51.5t51.5 21.5 51.5-21.5 21.5-51.5V533q0-30-21.5-51.5t-51.5-21.5zm506-250l38-64q6-10-4-16-9-6-15 4l-41 66q-50-18-117-18-68 0-118 19l-41-67q-6-10-15.5-4t-3.5 16l39 64q-118 58-118 226v15h512v-15q0-170-116-226zm-258 136q-12 0-20-8.5t-8-20.5 8-20 20-8 20.5 8 8.5 20-8.5 20.5-20.5 8.5zm237 0q-12 0-20.5-8.5t-8.5-20.5 8.5-20 20.5-8 20.5 8 8.5 20-8.5 20.5-20.5 8.5zm247 114q-30 0-51.5 21.5t-21.5 51.5v253q0 30 21.5 51.5t51.5 21.5 51.5-21.5 21.5-51.5V533q0-30-21.5-51.5t-51.5-21.5z","default_width":1036.3330078125,"title":"android","default_height":1152,"category":"asd3"}]'

JSON Response

[  
   "5afc83237bc52f686e5023c1"
]

DELETE

Delete icons in the KV store icon library.

Request parameters

Name Type Description
category String When set, deletes all icons in that category.

Data payload:
None.

Return
Success message.

Example request and response
To delete all icons from KV store:

curl -k -u admin:password https://localhost:8089/services/SA-ITOA/v1/icon_collection?category=* -X DELETE 

JSON Response

{  
   "Deleted":"True"
}

services/SA-ITOA/v1/icon_collection/<object identifier>

Delete a glass table icon. The object identifier is the _key field value for the icon.

DELETE

Deletes the icon provided in the _key.

Request parameters
None.

Data payload:
None.

Return
Success message.

Example request and response

curl -k -u admin:password https://localhost:8089/services/SA-ITOA/v1/icon_collection/5a9eb1e07bc52f76a2326e41 -X DELETE 

JSON Response

{  
   "Deleted":"True"
}
  NEXT
ITSI REST API schema

This documentation applies to the following versions of Splunk® IT Service Intelligence: 4.0.0, 4.0.1, 4.0.2, 4.0.3, 4.0.4, 4.1.0, 4.1.1, 4.1.2, 4.2.0, 4.2.1


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters