REST API Reference Manual

 


Introduction

Introduction

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.

Endpoint grouping

Endpoints are grouped in the following categories, which is how the API documentation is also organized.

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

Documentation conventions

The API documentation uses the following conventions to facilitate usability.

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.

Name Type Default Description
count Number 30 Maximum number of entries to return. Set value to zero 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 Collating sequence for sorting the response:

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.

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
200 Request completed successfully.
201 Create request completed successfully.
204 Request completed successfully but no content available to return.
400 Request error. See response body for details.
401 Authentication failure, invalid access credentials.
402 In-use Splunk license disables this feature.
403 Insufficient permission.
404 Requested endpoint does not exist.
409 Invalid operation for this endpoint. See response body for details.
500 Unspecified internal server error. See response body for details.
503 Feature is disabled in Splunk configuration file.

EAI response data

EAI response data, the <eia:acl> and <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.

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 the current user can change the entity's sharing state. The sharing state can be app, global, or private. Applies to:
  • can_share_app
  • can_share_global
  • can_share_user
can_write Indicates if the current user can edit this item.
owner The user that owns the resource.

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

modifiable Indicates if the Access Control List (ACL) is modifiable.

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 specific user.
  • EAI attributes - eai:attributes

The eai:attributes element shows the mandatory and optional requirements of each field.

Attribute Description
optionalFields Field is optional.
requiredFields Field is required.
wildcardFields Field can be specified using wildcard.

Example format

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

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.

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

This documentation applies to the following versions of Splunk: 6.0 , 6.0.1 , 6.0.2 , 6.0.3 , 6.0.4 , 6.0.5 , 6.1 , 6.1.1 , 6.1.2 View the Article History for its revisions.


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

Was this documentation topic helpful?

If you'd like to hear back from us, please provide your email address:

We'd love to hear what you think about this topic or the documentation as a whole. Feedback you enter here will be delivered to the documentation team.

Feedback submitted, thanks!