REST API reference and user guide
This is the Splunk Enterprise REST API, which gives detailed endpoint descriptions for accessing REST resources..
Read the REST API user guide section for basic concepts you need to know before using the API.
Endpoints are grouped in the following categories, which is how the API documentation is also organized.
|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.|
|Indexes||Manage data indexes.|
|Inputs||Manage data input.|
|Knowledge||Define indexed and searched data configurations.|
|Licensing||Manage licensing configurations.|
|Outputs||Manage forwarder data configuration.|
|Search||Manage searches and search-generated alerts and view objects.|
|System||Manage server configuration.|
The API documentation uses the following conventions for describing endpoints.
Pagination and filtering parameters
The following request parameters are valid for some GET methods, and the endpoint documentation indicates if the method supports common request parameters.
Conforming endpoints might not support all of these parameters.
|count||Number|| ||Maximum number of entries to return. Set value to zero to get all available entries.|
|offset||Number|| ||Index of first item to return.|
|search||String|| Response filter, where the response field values are matched against this search expression.
|sort_dir||Enum|| || Response sort order:
|sort_key||String|| ||Field name to use for sorting.|
|sort_mode||Enum|| || Collating sequence for sorting the response:
|summarize||Bool|| || Response type:
HTTP status codes
REST requests can return one or more of the following HTTP status codes:
Actual returned status codes are endpoint-dependent. Endpoint documentation notes any status codes with special significance or whose Splunk Enterprise-specific cause differs from the standard.
See the Hypertext Transfer Protocol -- HTTP/1.1, Status Code Definitions standard for the complete list of status codes and their meaning.
|Status code||Generalized description|
|Request completed successfully.|
|Create request completed successfully.|
|Request completed successfully but no content available to return.|
|Request error. See response body for details.|
|Authentication failure, invalid access credentials.|
|In-use Splunk license disables this feature.|
|Requested endpoint does not exist.|
|Invalid operation for this endpoint. See response body for details.|
|Unspecified internal server error. See response body for details.|
|Feature is disabled in Splunk configuration file.|
EAI response data
EAI response data, the
<eai:attributes> elements, are are not documented for each endpoint because they commonly apply to all endpoints and are configuration-specific. These elements are also elided from the response examples to make the documentation easier to understand.
- 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.
|app|| The app context for the resource. Allowed values are:
|can_list||For internal use only for the Splunk Web manager UI.|
|can_share_*|| Indicates whether the current user can change the entity's sharing state. The sharing state can be app, global, or private. Applies to:
|can_write||Indicates if the current user can edit this item.|
|owner|| The user that owns the resource.
A value of
|modifiable|| Indicates if the Access Control List (ACL) is modifiable.
Set to false for items not controlled by ACLs, such as items under
|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:
- EAI attributes - eai:attributes
eai:attributes element shows the mandatory and optional requirements of each field.
|optionalFields||Field is optional.|
|requiredFields||Field is required.|
|wildcardFields||Field can be specified using wildcard.|
Resource request format
The examples demonstrate typical endpoint access, using the cURL command line utility.
cURL is available with your *NIX distribution or from the following resources:
See the cURL manpage for command line options.
An example of the default XML response for a minimally configured system immediately follows the request.
You can also access endpoints 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
Powershell users can use Invoke-RestMethod
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.
- 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.