This documentation applies to the following versions of Splunk: 4.0 , 4.0.1 , 4.0.2 , 4.0.3 , 4.0.4 , 4.0.5 , 4.0.6
Splunk's API is RESTful, meaning that every communication with the API uses HTTP requests to interact with resources within Splunk. There are two main tasks you can do with Splunk's API: run searches and manage Splunk configurations and objects. The REST API is divided into endpoints, or URIs served off of 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.
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. To understand the difference between objects and configurations, see the developer configuration guide in this manual. Access objects from within a namespace -- specifying the app and user associated with the object. Access configurations directly.
Since Splunk's API is REST, it supports GET and POST. The management endpoints also support PUT and DELETE. Use a GET request to retrieve information from a resource and a POST update a resource. DELETE removes an entire resource while PUT updates an entire resource. After receiving your request, Splunk's API sends back an HTTP code an 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 this manual 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.
The URIs for configuration endpoints are served off of https://localhost:8089/services/.
The URIs for object endpoints are served off of https://localhost:8089/servicesNS/<user>/<app>. Use your installation host name and management port -- by default, 8089. Note that Splunk's API is secure, so use HTTPS whenever you access any endpoints.
Each endpoint gives you access to a different area of Splunk. For example, use the search endpoint to run searches and retrieve results. Use the data endpoint to manage inputs, outputs and indexes. Use the auth endpoint to authenticate, get a session key and interact with users and roles. The saved endpoint gives you access to saved searches and event types. Although there are more endpoints than these four, this manual focuses on these as most use cases can be met by accessing these four endpoints.
POST to an endpoint to update values or create a new configuration. For example, POST to the search endpoint to create a new search. GET from an endpoint to retrieve configurations or results. For example, GET from the search endpoint to retrieve search results.
To see a list of currently available generic endpoints, navigate to https://localhost:8089/services/ from your browser. To see app and user scoped endpoints, navigate to the servicesNS endpoint at https://localhost:8089/servicesNS/<user>/<app>/. For example, https://localhost:8089/servicesNS/admin/search/.
Click any endpoint to see what endpoints are served. For example, if you click data you'll see specific types of data inputs, index configuration and output/forwarding configuration options. If you click the create link, you'll see what parameters you can pass to that endpoint in a POST request.
Once you know which endpoint you want to GET and POST to, send REST requests the same way you send any HTTP request. From the command line, for example, you can use wget or curl. You can also build requests into your code, be it Java, .NET, perl, PHP, Python, Ruby...Just send your HTTP request to any available Splunk endpoint the way you'd handle any HTTP request.
Before you can interact with Splunk's endpoints, you'll need to authenticate. You can authenticate in your requests by using HTTP auth with curl. For example:
curl -u admin:changeme -k https://localhost:8089/services/
Note that you'll have to change the host/port and username/password to your own installation specifics.
This example just returns an XML list of all the available endpoints.
If you're going to send multiple requests, you'll want to generate an auth token for your entire session. Learn more about how to get an auth token.
Splunk's REST API returns and HTTP response code and results in XML (unless otherwise specified). The HTTP response code indicates whether you were successful (200) or whether something went wrong with your request (400, 500). The Python library shipping with Splunk includes lxml and ElementTree to parse XML responses.
Splunk returns XML responses as either ATOM feed or generic XML.
A generic response looks like:
<response> <sessionKey>30774f9d502004b5c655c08b5362bdca</sessionKey> </response>
An ATOM response looks like:
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xml" href="/static/atom.xsl"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest">
<title>services</title>
<id>https://localhost:8089/services/</id>
<updated>2008-01-31T19:15:37-0600</updated>
<generator version="31749"/>
<author>
<name>Splunk</name>
</author>
<entry>
<title>streams</title>
<id>https://localhost:8089/services/streams</id>
<updated>2008-01-31T19:15:37-0600</updated>
<link href="https://localhost:8089/services/streams" rel="alternate"/>
</entry>
...
...
</feed>
Splunk's built in Python libraries support getting elements from the XML response. Most XML available XML parsing libraries offer support for this, as well. For example, use XPath (supported in JavaScript, Java and C#).
Splunk currently provides SDKs -- wrapper functions, methods and modules for the REST API -- in Python and Java.
Splunk ships with a built-in SDK. You can access the available methods by running Pydoc from the command line. More on the Python SDK.
There is an open-source Java SDK project available at Google code. Please note that this SDK is not currently supported. You can, however, request help on the Splunk Google code forums.
Java SDK is available here: