REST API Overview

The Splunk REST API

An API (Application Programming Interface) is a set of defined interfaces to accomplish a task, such as retrieving or modifying data. In Splunk®'s case, we provide an API method for every feature in our product. Programmers can use our API to make applications, phone apps, widgets, and other projects that interact with Splunk. Programs talk to the Splunk API over HTTP , the same protocol that your web browser uses to interact with web pages, and conforms to the principles of Representational State Transfer (REST).

There are two broad categories of tasks you can do with Splunk's REST API: run searches and manage Splunk configurations and objects. The REST API is divided into endpoints, or URIs served by the Splunk server (splunkd). All management endpoints behave the same, meaning they take the same global parameters and return responses in the same format. The search endpoints are special cases and behave differently from the configuration endpoints.

Since Splunk's API is REST, it supports GET, POST, and DELETE requests. Use a GET request to retrieve information from a resource and a POST to update an entity. DELETE removes an entity. After receiving your request, Splunk's API sends back an HTTP code and a response in XML (unless otherwise specified). If you're not familiar with REST or HTTP, we suggest you check out the Wikipedia articles on Representational State Transfer and Hypertext Transfer Protocol.

You can make requests to Splunk's API from a terminal or browser, or within any code. The examples in these tutorials use curl, but you can use wget, libcurl or any other method to GET and POST in your preferred language. You'll probably want some way to parse the XML responses, too. Your preferred coding language should include libraries to support making HTTP requests and parsing XML responses.

There are two ways to access management endpoints, depending on whether you'll be working with an object or a configuration. Objects are configurations within Splunk that are scoped to users and apps. For example, saved searches, event types and fields are objects. Indexes, inputs, users and roles are configurations. Access objects from within a namespace -- specifying the app and user associated with the object. Access configurations directly.

Common HTTP Status Codes

For all requests to the REST endpoints, the HTTP server will return one of following status codes. See the reference docs for each particular endpoint to know which status codes it's capable of returning, so your code can handle all contingencies.

Status

Description

200
Operation successful.
201
Object created successfully.
204
Successful, but no content was returned.
401
Authentication failure: must pass valid credentials with request. Session may have timed out.
402
The Splunk license in use has disabled this feature.
403
Insufficient permissions to view/edit/create/disable/delete.
404
Object does not exist.
405
Method Not Allowed (e.g. supports GET but not POST)
409
Request error: this operation is invalid for this item. See response body for explanation.
500
Internal server error. See response body for explanation.
503
This feature has been disabled in Splunk configuration files.

Authentication Methods

There are two methods of authenticating with the Splunkd HTTP server.

  • HTTP Header -- Splunkd supports token-based authentication via the standard HTTPAuthorization header. This is the recommended method for most programmatic accesses against the API.
    1. Obtain a session key via the /services/auth/login endpoint, i.e.71e2f3553ba1dd279e36a6920a1e7840.
    2. Insert the session key into the Authorization header of every subsequent request, as follows:
      Authorization: Splunk 71e2f3553ba1dd279e36a6920a1e7840
  • HTTP Basic -- Splunkd supports basic access authentication, as defined by RFC 1945. This is the method that is invoked when you browse the HTTP server from a web browser.

Global pagination and filtering

All endpoints that return lists of objects adhere to a standard interface for paging and filtering of their list output.

Request

Any endpoint that returns a list of objects in an Atom feed format provides paging and filtering capabilities via these params:

offset
The starting offset (0-based) of the first object to return in the list. Default value is 0.
count
The maximum number of objects to return, starting from offset. 0 returns all objects. Default value is 30.
earliest_time
Filters the returned objects by their timestamp. Only objects that have a timestamp that is >= earliest_time will be returned. For Atom feeds, the relevant date is thepublished property. However, if the Atom entry uses an updated property, that is used instead. The time format is always ISO-8601 formatted. Ex:2008-01-29T11:40:58-0800. If omitted, then no earliest time bound is used.
latest_time
Filters the returned objects by their timestamp. Only objects that have a timestamp that is < latest_time will be returned. For Atom feeds, the relevant date is thepublished property. However, if the Atom entry uses an updated property, that is used instead. The time format is always ISO-8601 formatted. Ex:2008-01-29T11:40:58-0800. If omitted, then no latest time bound is used.
search
Filters the returned objects by matching any eligible field value against the search expression. For example: search=foo would match any object that has the value 'foo' as a substring of at least one of the eligible fields. The search can also be restricted to a single field as follows: search=field_name%3Dfield_value (which when URL decoded is: field_name=field_value).
sort_key
The field on which to sort the returned results. If the field is not present on an entry, the empty string value is used. Default value is name.
sort_dir
[ asc desc ] The direction of the sort. Default value is asc.
sort_mode
[ auto alpha alpha_case num ] Comparison method to use when sorting: auto - if all values of the field are numbers use numeric otherwise alpha, alpha - case insensitive string comparison, alpha_case - case sensitive string comparison or num - numeric comparison. Default value auto.

Response

Endpoints that return Atom feeds will convey pagination information via the OpenSearch extension to Atom. Additions to the standard Atom feed XML are:

  • Opensearch namespace declaration
  • totalResults node
  • startIndex node
  • itemsPerPage node
// sample response to request to saved searches: /services/saved/searches?offset=12&count=34
// the server has a total 765 saved searches

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
      xmlns:s='http://dev.splunk.com/ns/rest'>
      xmlns:opensearch='http://a9.com/-/spec/opensearch/1.1/'>
    <title>Indexes</title>
    <id>https://127.0.0.1:23424/services/data/indexes</id>
    <opensearch:totalResults>765</opensearch:totalResults>
    <opensearch:startIndex>12</opensearch:startIndex>
    <opensearch:itemsPerPage>34</opensearch:itemsPerPage>
    ....
</feed>

Object Sharing and Permissions

All endpoints that list user objects support object sharing and Access Control List (ACL) presentation and mutation. An ACL consists of the following fields:

modifiable
Required. A boolean flag indicating whether the ACL is modifiable or not.
owner
Required. Username of the owner of this object, if an object is not owned by a user should be set to 'nobody'
perms
Required. A dictionary that maps action to a list of roles which can perform that action
sharing
The level at which this object is shared, can be one of: system, app, user, global

A request to modify the ACL of an object should POST on the 'acl' custom action of an object (url: ...endpoint/entity-name/acl). The entire ACL should be provided rather than a diff. The following parameters should be provided:

perms.<action>
A comma delimited list of roles which can perform the given action
owner
The username of the new owner of the object
sharing
The level at which this object is shared, can be one of: system, app, user, global