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

System endpoint descriptions

Manage server configuration settings and messages.

Usage details

Authentication and Authorization
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.

Additional information
See Introspection endpoint descriptions for the system endpoints related to introspection.

messages

https://<host>:<mPort>/services/messages


Access and create system messages. Most messages are created by splunkd to inform the user of system information, including license quotas, license expirations, misconfigured indexes, and disk space. Splunk Web displays these as bulletin board messages.


GET

Enumerate all systemwide messages.

Request parameters
Pagination and filtering parameters can be used with this method.

Response keys
Depending on the system status, messages returned vary. Messages returned in the response include a name and description, as in the following example.

Name Description
restart_required System message indicating that restarting is required.


Example request and response

XML Request

curl -k -u admin:changeme https://localhost:8089/services/messages

XML Response

.
.
.
 <title>messages</title>
 <id>https://localhost:8089/services/messages</id>
 <updated>2011-07-08T01:14:21-07:00</updated>
 <generator version="102807"/>
 <author>
   <name>Splunk</name>
 </author>
 <link href="/services/messages/_new" rel="create"/>
    ... opensearch elements elided ...
 <s:messages/>
 <entry>
   <title>restart_required</title>
   <id>https://localhost:8089/services/messages/restart_required</id>
   <updated>2011-07-08T01:14:21-07:00</updated>
   <link href="/services/messages/restart_required" rel="alternate"/>
   <author>
     <name>system</name>
   </author>
   <link href="/services/messages/restart_required" rel="list"/>
   <link href="/services/messages/restart_required" rel="remove"/>
   <content type="text/xml">
     <s:dict>
       ... eai:acl node elided ...
       <s:key name="restart_required">Splunk must be restarted for changes to take effect.</s:key>
     </s:dict>
   </content>
 </entry>


POST

Create a persistent message displayed at /services/messages.

Request parameters

Name Type Description
<name> String Required. Message name (key).
value String Required. Message text.
severity String Message severity level:
info: Informative
warn: Warning condition
error: Error condition

Response keys
None


Example request and response


XML Request

curl -k -u admin:changeme https://localhost:8089/services/messages -d name=helloMessage -d value="hello world" -d severity="info"

XML Response

.
.
.
<title>messages</title>
 <id>https://localhost:8089/services/messages</id>
 <updated>2014-02-20T10:24:02-08:00</updated>
 <generator build="197187" version="6.1beta"/>
 <author>
   <name>Splunk</name>
 </author>
 <link href="/services/messages/_new" rel="create"/>
    ... opensearch elements elided ...
 <s:messages/>
 <entry>
   <title>helloMessage</title>
   <id>https://localhost:8089/services/messages/helloMessage</id>
   <updated>2014-02-20T10:24:02-08:00</updated>
   <link href="/services/messages/helloMessage" rel="alternate"/>
   <author>
     <name>system</name>
   </author>
   <link href="/services/messages/helloMessage" rel="remove"/>
   <content type="text/xml">
     <s:dict>
       <s:key name="helloMessage">"hello world"</s:key>
       <s:key name="eai:acl">
          ... elided ...
       </s:key>
       <s:key name="message">"hello world"</s:key>
       <s:key name="severity">info</s:key>
       <s:key name="timeCreated_epochSecs">1392920642</s:key>
     </s:dict>
   </content>
 </entry>

messages/{name}

https://<host>:<mPort>/services/messages/{name}


Manage the message associated with the {name} message ID.


DELETE

Delete the specified message.

Request parameters
None

Response keys
None. An HTTP status code = 500 is returned if {name} message does not exist.

Example request and response

XML Request

curl -k -u admin:changeme --request DELETE https://localhost:8089/services/messages/message

XML Response

.
.
.
 <title>messages</title>
 <id>https://localhost:8089/services/messages</id>
 <updated>2011-07-08T01:14:21-07:00</updated>
 <generator version="102807"/>
 <author>
   <name>Splunk</name>
 </author>
 <link href="/services/messages/_new" rel="create"/>
    ... opensearch elements elided ...
 <s:messages/>


GET

Get details of the specified message.

Request parameters
None

Response keys

Name Description
message The specified system message.


Example request and response

XML Request

curl -k -u admin:changeme https://localhost:8089/services/messages/message

XML Response

.
.
.
<title>messages</title>
 <id>https://localhost:8089/services/messages</id>
 <updated>2011-07-08T01:14:21-07:00</updated>
 <generator version="102807"/>
 <author>
   <name>Splunk</name>
 </author>
 <link href="/services/messages/_new" rel="create"/>
    ... opensearch elements elided ...
 <s:messages/>
 <entry>
   <title>message</title>
   <id>https://localhost:8089/services/messages/message</id>
   <updated>2011-07-08T01:14:21-07:00</updated>
   <link href="/services/messages/message" rel="alternate"/>
   <author>
     <name>system</name>
   </author>
   <link href="/services/messages/message" rel="list"/>
   <link href="/services/messages/message" rel="remove"/>
   <content type="text/xml">
     <s:dict>
       ... eai:acl node elided ...
       <s:key name="eai:attributes">
         <s:dict>
           <s:key name="optionalFields">
             <s:list/>
           </s:key>
           <s:key name="requiredFields">
             <s:list/>
           </s:key>
           <s:key name="wildcardFields">
             <s:list/>
           </s:key>
         </s:dict>
       </s:key>
       <s:key name="message">hello world</s:key>
     </s:dict>
   </content>
 </entry>

server/control

https://<host>:<mPort>/services/server/control


List available controls.

GET

List actions that can be performed at this endpoint.


Request parameters
None

Response keys
None

Example request and response

XML Request

curl -k -u admin:changeme https://localhost:8089/services/server/control

XML Response

.
.
.
 <title>server-control</title>
 <id>https://localhost:8089/services/server/control</id>
 <updated>2011-07-12T00:17:53-07:00</updated>
 <generator version="102807"/>
 <author>
   <name>Splunk</name>
 </author>
 <link href="/services/server/control/restart" rel="restart"/>
    ... opensearch elements elided ...
 <s:messages/>

server/control/restart

https://<host>:<mPort>/services/server/control/restart

Restart the splunkd server daemon and Splunk Web interface. The POST operation is equivalent to the splunk restart CLI command.

See also server/control/restart_webui


POST

Restart the splunkd server daemon and Splunk Web interface.


Request parameters
None

Response keys
An HTTP status code 200 indicates successful restart.

Example request and response


XML Request

curl -k -u admin:changeme https://localhost:8089/services/server/control/restart -X POST

XML Response

.
.
.
 <title>server-control</title>
 <id>https://localhost:8089/services/server/control</id>
 <updated>2014-08-05T13:02:50-07:00</updated>
 <generator build="221120" version="6.2"/>
 <author>
   <name>Splunk</name>
 </author>
 <link href="/services/server/control/restart" rel="restart"/>
 <link href="/services/server/control/restart_webui" rel="restart_webui"/>
 ... opensearch nodes elided ...
 <s:messages/>

server/control/restart_webui

https://<host>:<mPort>/services/server/control/restart_webui


Restart the Splunk Web interface. This interface is equivalent to the splunk restart splunkweb CLI command, and restarts the Web interface on servers with the default app server mode set. See also server/control/restart


POST

Restart the Splunk Web interface.


Request parameters
None

Response keys
An HTTP status code 200 indicates successful restart.

Example request and response

XML Request

curl -k -u admin:changeme https://localhost:8089/services/server/control/restart_webui -X POST


XML Response

.
.
.
 <title>server-control</title>
 <id>https://localhost:8089/services/server/control</id>
 <updated>2014-08-05T12:10:37-07:00</updated>
 <generator build="221120" version="6.2"/>
 <author>
   <name>Splunk</name>
 </author>
 <link href="/services/server/control/restart" rel="restart"/>
 <link href="/services/server/control/restart_webui" rel="restart_webui"/>
 ... opensearch elements elided ...
 <s:messages/>

server/logger

https://<host>:<mPort>/services/server/logger


Access splunkd logging categories specified in code or in $SPLUNK_HOME/etc/log.cfg.


GET

Enumerate splunkd logging categories.


Request parameters
Pagination and filtering parameters can be used with this method.

Response keys

Name Description
level One of the following valid logger levels for this server.
  • FATAL
  • WARN
  • INFO
  • DEBUG

Example request and response

XML Request

curl -k -u admin:changeme https://localhost:8089/services/server/logger

XML Response

.
.
.
<title>logger</title>
 <id>https://mrt:8089/services/server/logger</id>
 <updated>2011-05-16T20:29:38-0700</updated>
 <generator version="98144"/>
 <author>
   <name>Splunk</name>
 </author>
    ... opensearch elements elided ...
 <s:messages/>
 <entry>
   <title>AdminHandler:AuthenticationHandler</title>
   <id>https://mrt:8089/services/server/logger/AdminHandler%3AAuthenticationHandler</id>
   <updated>2011-05-16T20:29:38-0700</updated>
   <link href="/services/server/logger/AdminHandler%3AAuthenticationHandler" rel="alternate"/>
   <author>
     <name>system</name>
   </author>
   <link href="/services/server/logger/AdminHandler%3AAuthenticationHandler" rel="list"/>
   <link href="/services/server/logger/AdminHandler%3AAuthenticationHandler" rel="edit"/>
   <content type="text/xml">
     <s:dict>
       <s:key name="eai:acl">... elided ...</s:key>
       <s:key name="level">WARN</s:key>
     </s:dict>
   </content>
 </entry>
       .
       .
       .
     elided
       .
       .
       .
 <entry>
   <title>Application</title>
   <id>https://mrt:8089/services/server/logger/Application</id>
   <updated>2011-05-16T20:29:38-0700</updated>
   <link href="/services/server/logger/Application" rel="alternate"/>
   <author>
     <name>system</name>
   </author>
   <link href="/services/server/logger/Application" rel="list"/>
   <link href="/services/server/logger/Application" rel="edit"/>
   <content type="text/xml">
     <s:dict>
       <s:key name="eai:acl">... elided ...</s:key>
       <s:key name="level">WARN</s:key>
     </s:dict>
   </content>
 </entry>
 <entry>
   <title>ApplicationManager</title>
   <id>https://mrt:8089/services/server/logger/ApplicationManager</id>
   <updated>2011-05-16T20:29:38-0700</updated>
   <link href="/services/server/logger/ApplicationManager" rel="alternate"/>
   <author>
     <name>system</name>
   </author>
   <link href="/services/server/logger/ApplicationManager" rel="list"/>
   <link href="/services/server/logger/ApplicationManager" rel="edit"/>
   <content type="text/xml">
     <s:dict>
       <s:key name="eai:acl">... elided ...</s:key>
       <s:key name="level">WARN</s:key>
     </s:dict>
   </content>
 </entry>

server/logger/{name}

https://<host>:<mPort>/services/server/logger/{name}


Manage the {name} logging category.


GET

Access information about the specified splunkd logging category.

Request parameters
None

Response keys

Name Description
level One of the following valid logger levels for this server.
  • FATAL
  • WARN
  • INFO
  • DEBUG

Example request and response


XML Request

curl -k -u admin:changeme https://localhost:8089/services/server/logger/Application

XML Response

.
.
.
<title>logger</title>
 <id>https://localhost:8089/services/server/logger</id>
 <updated>2011-07-02T15:10:44-07:00</updated>
 <generator version="100492"/>
 <author>
   <name>Splunk</name>
 </author>
    ... opensearch elements elided ...
 <s:messages/>
 <entry>
   <title>Application</title>
   <id>https://localhost:8089/services/server/logger/Application</id>
   <updated>2011-07-02T15:10:44-07:00</updated>
   <link href="/services/server/logger/Application" rel="alternate"/>
   <author>
     <name>system</name>
   </author>
   <link href="/services/server/logger/Application" rel="list"/>
   <link href="/services/server/logger/Application" rel="edit"/>
   <content type="text/xml">
     <s:dict>
       <s:key name="eai:acl">... elided ...</s:key>
       <s:key name="eai:attributes">
         <s:dict>
           <s:key name="optionalFields">
             <s:list/>
           </s:key>
           <s:key name="requiredFields">
             <s:list>
               <s:item>level</s:item>
             </s:list>
           </s:key>
           <s:key name="wildcardFields">
             <s:list/>
           </s:key>
         </s:dict>
       </s:key>
       <s:key name="level">WARN</s:key>
     </s:dict>
   </content>
 </entry>


POST

Set the logging level for a specific logging category.


Request parameters

Name Type Description
level Enum Required. The desired logging level for this category.
One of the following valid values.

[FATAL | WARN | INFO | DEBUG]

Response keys
None


Example request and response


XML Request

curl -k -u admin:changeme https://localhost:8089/services/server/logger/Application -d level=INFO

XML Response

.
.
.
 <title>logger</title>
 <id>https://localhost:8089/services/server/logger</id>
 <updated>2011-07-07T00:24:02-07:00</updated>
 <generator version="102807"/>
 <author>
   <name>Splunk</name>
 </author>
 <s:messages/>

server/roles

https://<host>:<mPort>/services/server/roles


Access server role information.

See also the server-roles attribute in /server/info.


GET

Access the roles applicable to this server.

Request parameters
None

Response keys

Name Description
<variable> Zero or more of the following possible server roles.
  • indexer
  • universal_forwarder
  • heavyweight_forwarder
  • lightweight_forwarder
  • license_master
  • license_slave
  • cluster_master
  • cluster_slave
  • cluster_search_head
  • deployment_server
  • deployment_client
  • search_head
  • search_peer
  • shc_captain
  • shc_deployer
  • shc_member


Example request and response

XML Request

curl -k -u admin:changeme https://localhost:8089/services/server/roles

XML Response

.
.
.
 <title>server-roles</title>
 <id>https://localhost:8089/services/server/roles</id>
 <updated>2014-04-02T12:13:07-07:00</updated>
 <generator build="200839" version="6.1"/>
 <author>
   <name>Splunk</name>
 </author>
 <link href="/services/server/roles/catalog_allPossible_predefined" rel="catalog_allPossible_predefined"/>
   ... opensearch elements elided ...
 <s:messages/>
 <entry>
   <title>result</title>
   <id>https://localhost:8089/services/server/roles/result</id>
   <updated>2014-04-02T12:13:07-07:00</updated>
   <link href="/services/server/roles/result" rel="alternate"/>
   <author>
     <name>system</name>
   </author>
   <link href="/services/server/roles/result" rel="list"/>
   <content type="text/xml">
     <s:dict>
       <s:key name="eai:acl">
           ... elided ...
       </s:key>
       <s:key name="indexer"/>
       <s:key name="license_master"/>
       <s:key name="license_slave"/>
     </s:dict>
   </content>
 </entry>

server/settings

https://<host>:<mPort>/services/server/settings


Access server configuration information for a Splunk platform instance.


GET

Returns server configuration for a Splunk platform instance.


Request parameters
Pagination and filtering parameters can be used with this method.

Response keys

Name Description
SPLUNK_DB Absolute filepath to the default index for this instance.
SPLUNK_HOME Absolute filepath to the local installation of this instance.
enableSplunkWebSSL Indicates if HTTPS and SSL are enabled for Splunk Web.
host The default hostname to use for data inputs that do not override this setting.
httpport Port on which Splunk Web listens for this instance.
Defaults to 8000. If using SSL, set to the HTTPS port number.
mgmtHostPort The port on which Splunk Web listens for management operations. Defaults to 8089.
minFreeSpace Safe amount of space in MB that must exist for splunkd to continue operating.
minFreespace affects search and indexing in the following ways.
  • Before attempting to launch a search, the Splunk platform requires this amount of free space on the filesystem where the dispatch directory is stored, $SPLUNK_HOME/var/run/splunk/dispatch.
  • Applied similarly to the search quota values in authorize.conf and limits.conf.
  • For indexing, periodically, the indexer checks space on all partitions that contain splunk indexes as specified by indexes.conf. When you need to clear more disk space, indexing is paused and the Splunk platform posts a UI banner + warning.
pass4SymmKey Password string prefixed to the Splunk platform symmetric key, generating the final key to sign all traffic between master/slave licenser.
serverName Name identifying this instance for features such as distributed search.
sessionTimeout Time range string to indicate the amount of time before a user session times out. Expressed as a search-like time range. The default is 1h (one hour).
Here are some examples.

24h (24 hours)

3d (3 days)

7200s (7200 seconds, or two hours)

startwebserver Indicates whether Splunk Web is configured to start by default.
trustedIP IP address of the authenticating proxy. Set to a valid IP address to enable SSO.
Disabled by default. Normal value is '127.0.0.1'


Example request and response

XML Request

curl -k -u admin:changeme https://localhost:8089/services/server/settings

XML Response

.
.
.
<title>server-settings</title>
 <id>https://localhost:8089/services/server/settings</id>
 <updated>2011-07-08T01:56:40-07:00</updated>
 <generator version="102807"/>
 <author>
   <name>Splunk</name>
 </author>
    ... opensearch elements elided ...
 <s:messages/>
 <entry>
   <title>settings</title>
   <id>https://localhost:8089/services/server/settings/settings</id>
   <updated>2011-07-08T01:56:40-07:00</updated>
   <link href="/services/server/settings/settings" rel="alternate"/>
   <author>
     <name>system</name>
   </author>
   <link href="/services/server/settings/settings" rel="list"/>
   <link href="/services/server/settings/settings" rel="edit"/>
   <content type="text/xml">
     <s:dict>
       <s:key name="SPLUNK_DB">/home/amrit/temp/curl/splunk/var/lib/splunk</s:key>
       <s:key name="SPLUNK_HOME">/home/amrit/temp/curl/splunk</s:key>
       ... eai:acl node elided ...
       <s:key name="enableSplunkWebSSL">0</s:key>
       <s:key name="host">MrT</s:key>
       <s:key name="httpport">8001</s:key>
       <s:key name="mgmtHostPort">8085</s:key>
       <s:key name="minFreeSpace">2000000</s:key>
       <s:key name="pass4SymmKey">changeme</s:key>
       <s:key name="serverName">MrT</s:key>
       <s:key name="sessionTimeout">1h</s:key>
       <s:key name="startwebserver">1</s:key>
       <s:key name="trustedIP"/>
     </s:dict>
   </content>
 </entry>

PREVIOUS
Search endpoint examples
  NEXT
System endpoint examples

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