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>
isnobody
and<app>
isSA-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 . 0 must have the required fields for the object schema provided. Example: For the service object type, title is the required field, and without this field, is_partial_data with 0 will not work. 0 will update the fields in the original schema of the object schema provided as well as wrong fields which are not in the original schema.
|
Note: is_partial_data= (no parameter) will work same as is_partial_data=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, |
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:
|
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.
|
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/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 categoryimmutable
- 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" }
ITSI REST API schema |
This documentation applies to the following versions of Splunk® IT Service Intelligence: 4.13.0, 4.13.2, 4.13.3, 4.14.0 Cloud only, 4.14.1 Cloud only, 4.14.2 Cloud only
Feedback submitted, thanks!