Splunk® Enterprise

REST API Reference Manual

Download manual as PDF

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

About the REST API Reference

This manual gives summary and detailed endpoint descriptions for REST resources.

See the REST API User Manual for introductory information about using the REST API.

Resource groups

The documentation groups resources into the following categories.

Category Description
Access control Authorize and authenticate users.
Applications Install applications and application templates.
Clusters Configure and manage cluster master and peer nodes.
Configuration Manage configuration files and settings.
Deployment Manage deployment servers and clients.
Inputs Manage data input.
Introspection Access system properties.
Knowledge Define indexed and searched data configurations.
KV store Manage app key-value store.
Licensing Manage licensing configurations.
Outputs Manage forwarder data configuration.
Search Manage searches and search-generated alerts and view objects.
System Manage server configuration.


References

Splunk Enterprise REST API documentation

Tools

Entry format

The API documentation uses the following formatting conventions to describe the resource interface.

Name

Endpoint descriptions use the URI as the endpoint name, beginning with the resource name. For example,

apps/appinstall

is the name of the

/services/apps/appinstall

or

/servicesNS/<user>/<app>/apps/appinstall

endpoint.

Deprecated methods have the "[DEPRECATED]" string after the name.


Description

The Description section gives a short description of the endpoint function. See the method Application usage section for application considerations about how to use the interface.

  • Note: Username and password authentication is required for most endpoints and REST operations. Additional capability or role-based authorization may also be required, particularly for POST or DELETE operations.


Method summary

A table listing the methods supported by the API, for this endpoint. Entries include the method name (operation) with a link to the method, a short description of the method function, and the supported data formats.

Method detail with examples

For each method listed in the method summary, DELETE, GET, and POST methods provide more detailed information about the method.

Click the Example link to view example API request and response calls.

Simple examples of how to make a request on the endpoint and what the response data looks like.

Your system must be configured appropriately to get the response shown in the examples. For example, a dynamic job ID parameter can be expected to be different for your setup. If needed, you can modify the examples to match your system configuration and state, including changing the hostname and port number.

Example request format

The examples show typical endpoint request syntax using the cURL command-line utility, unless another mechanism is more appropriate for the endpoint.


An example of the default XML response for a minimally configured system follows the request.

You can also access endpoints by using the httplib2 Python library distributed with Splunk Enterprise. For example: 

import httplib2

hostName = "localhost"
managementPort = "8089"
userName ="admin"
userPassword = "changeme"
testUri = "/services/apps/local"

h = httplib2.Http(".cache", disable_ssl_certificate_validation=True)
h.add_credentials(userName, userPassword)

base_url = "https://" + hostName + ":" + managementPort

try:
    response, content = h.request(base_url + testUri, "GET")
    if (response['status'] >= '200' and response['status'] <= '204'):
        print content
    else:
        print response['status']
except Exception, e:
    print "Exception: '%s'" % e

REST client browser plugins are a convenient way to exercise the REST API, and are available for all popular browsers. See #References.

Powershell users can use Invoke-RestMethod.

Example response format

To improve readability, the following response elements are elided using the ... elided ... notation.

  • opensearch node

Most responses include <opensearch> elements for paging. The opensearch elements are elided to improve readability.

  • Access Control List

All responses include an Access Control List (ACL) element that defines permissions for accessing the endpoint. The <eia:acl> element is elided to improve readability.

  • Note: Append /acl to an endpoint to access its ACL properties. For more information, see Access Control List in the REST API User Manual.
  • EIA attributes

Some GET responses include an EIA attribute element that defines required, optional, and wildcard endpoint elements. The <eai:attributes> element is elided to improve readability.

  • Multiple data content entries

Multiple data content entries might be elided to improve readability.

Request parameters

A list of support request parameters are described in terms of parameter name, datatype, default value, and a short description.

Required parameters are indicated by the required string with the parameter name.

Pagination and filtering parameters

The following request parameters are valid for some GET methods, as the endpoint documentation indicates.

Conforming endpoints might not support all of these parameters.

Name Datatype Default Description
count Number 30 Maximum number of entries to return. Set value to -1 to get all available entries.
offset Number 0 Index of first item to return.
search String Response filter, where the response field values are matched against this search expression.

Example:

search=foo matches on any field with the string foo in the name.
search=field_name%3Dfield_value restricts the match to a single field. (Requires URI-encoding.)

sort_dir Enum asc Response sort order:

asc = ascending
desc = descending

sort_key String name Field name to use for sorting.
sort_mode Enum auto Collated ordering:

auto = If all field values are numeric, collate numerically. Otherwise, collate alphabetically.
alpha = Collate alphabetically, not case-sensitive.
alpha_case = Collate alphabetically, case-sensitive.
num = Collate numerically.

summarize Bool false Response type:

true = Summarized response, omitting some index details, providing a faster response.
false = full response.

Response data keys

Response content data are key-value pairs. All valid parameters are listed with their name and description.

HTTP status codes

Responses can include one of the following HTTP status codes, in addition to content data. Status codes are not listed because the API generally follows the HTTP standard for reporting status. But, the documentation does note status codes with special significance or where the cause differs from the standard.

Error messages

In addition to the HTTP status code, many request error conditions also return an error message. For example: 

<response>
  <messages>
    <msg type="ERROR">
      In handler 'datamodelgenerate': The following required arguments are missing: sid.
    </msg>
  </messages>
</response>

EAI response data

EAI response data, the <eai:acl> and <eai:attributes> elements, typically apply to all endpoints and are configuration-dependent, so redundant explanation is omitted. These elements are also elided from the response examples to make the documentation easier to read.

  • Access Control List (ACL) [eai:acl]

The REST implementation enforces ownership and permissions for a resource based on application context namespace. The ACL includes the following parameters.


Parameter Description
app The app context for the resource. Allowed values are:
  • The name of an app
  • system
can_list For internal use only for the Splunk Web manager UI.
can_share_* Indicates whether or not the current user can change the sharing state. The sharing state can be one of:
  • can_share_app = App-level sharing
  • can_share_global = Global sharing
  • can_share_user = User-level sharing
can_write Indicates whether or not the current user can edit this item.
owner The user that owns the resource.

A value of nobody indicates that all users have access to the resource, but that write access to the resource might be restricted.

modifiable Indicates whether or not you can change the Access Control List (ACL).

Set to false for items not controlled by ACLs, such as items under /server/logger.

perms.read Properties that indicate read permissions of the resource.
perms.write Properties that indicate write permissions of the resource.
removable Indicates if an admin or user with sufficient permissions can remove the entity.
sharing Indicates how the resource is shared. Allowed values are:
  • app = Shared through an app.
  • global = Shared to all apps.
  • user = Private to a user.
  • Note: You can append /acl to an endpoint to access its ACL properties. For more information, see Access Control List in the REST API User Manual.
  • EAI attributes [eai:attributes]

The eai:attributes element shows the mandatory and optional fields.

Attribute Description
optionalFields Field is optional.
requiredFields Field is required.
wildcardFields Field can use wildcard.

Application usage

The Application usage section gives detailed information on the intended use of the method for the endpoint.

See also

If applicable, the See also section has links to related endpoints and documentation.

  NEXT
URI quick reference

This documentation applies to the following versions of Splunk® Enterprise: 6.2.0, 6.2.1, 6.2.2, 6.2.3, 6.2.4, 6.2.5, 6.2.6, 6.2.7, 6.2.8, 6.2.9, 6.2.10, 6.2.11, 6.2.12, 6.2.13, 6.2.14, 6.2.15, 6.3.0, 6.3.1, 6.3.2, 6.3.3, 6.3.4, 6.3.5, 6.3.6, 6.3.7, 6.3.8, 6.3.9, 6.3.10, 6.3.11, 6.3.12, 6.3.13, 6.3.14, 6.4.0, 6.4.1, 6.4.2, 6.4.3, 6.4.4, 6.4.5, 6.4.6, 6.4.7, 6.4.8, 6.4.9, 6.4.10, 6.4.11

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