Documentation > Splunk > REST API Reference > About the Splunk REST API

REST API Reference

 


REST API reference
Using Splunk's REST API

About the Splunk REST API

Contents

About the Splunk REST API

Splunk's API is RESTful

Splunk's API is RESTful, which means it uses HTTP requests to interact with resources within Splunk. Both Splunk Web and the Splunk CLI use Splunk’s REST API to communicate with a Splunk instance. You can use the REST API to configure and manage a Splunk instance, create and run searches in Splunk, or create your own applications that interact with Splunk.

You can use any language or tool that supports HTTP calls to access the Splunk REST API.

Note: The Splunk REST API Reference examples use cURL to illustrate REST access to Splunk resources. However, you can use wget, libcurl or any other method to access the REST API.

Accessing Splunk resources

Splunk resources are identified as URLs that map to endpoints. You can access the resources using a web browser, curl or other command line tools, or through program language tools.

splunkd is the server for the REST API endpoints. The Splunk REST API Reference categorizes and lists the endpoints available for development.

You can view the endpoints available in a Splunk instance using a web browser pointing to the Splunk management port. 

https://localhost:8089/services

For example, the following curl command creates a search: 

curl -u admin:pass \
     -k https://localhost:8089/services/search/jobs \
     -d "search=search *"

Note: 8089 is the default Splunk management port. The management port in your Splunk installation may vary. Examples in this reference use the default managment port.

Accessing Splunk version-specific REST endpoints

Currently, there has been little change in the REST API between versions. However, REST endpoint behavior can change based on a specific release of Splunk, including bug-fix releases. To ensure that you retrieve the results for a specific version, you can embed the version number in the REST API call. Here are the options available for making Splunk REST API requests:

Newest endpoint behavior

curl -u admin:pass -k https://localhost:8089/services/services/apps/local


Request behavior for a major version

curl -u admin:pass -k https://localhost:8089/v5/services/services/apps/local


Request behavior for a point release

curl -u admin:pass -k https://localhost:8089/v5.0.2/services/services/apps/local

Note: When accessing a prior version of Splunk, consult the Splunk documentation for that version.

API differences between Splunk 5.0 and Splunk 4.3

This version of the Splunk REST API Reference documents endpoints available for Splunk 5.0. With few exceptions, endpoints available in Splunk 5.0 are also available in Splunk 4.3

JSON output change for some search endpoints

The output mode for various search endpoints have changed, and now provide more choices for JSON and other output formats. This affects the endpoints listed below.

See JSON and other response formats for details.

GET search/fields
GET search/fields/{field_name}
GET search/jobs/export
GET search/jobs/{search_id}/events
GET search/jobs/{search_id}/results
GET search/jobs/{search_id}/results_preview
GET search/parser
GET search/tags/{tag_name}
GET search/timeparser
GET search/typeahead

Changed endpoints in Splunk 5.0

POST apps/local
POST apps/local/{name}

The following parameter has been deprecated in Splunk 5.0.

Name Type Description
manageable Boolean Deprecated in Splunk 5.0. Indicates that the Splunk Manager can manage the app.


POST data/indexes
POST data/indexes/{name}

The following parameters are new in Splunk 5.0.

Name Type Required Default Description
bucketRebuildMemoryHint String auto Suggestion for the Splunk bucket rebuild process for the size of the time-series (tsidx) file to make.

Caution: This is an advanced parameter. Inappropriate use of this parameter causes splunkd to not start if rebuild is required. Do not set this parameter unless instructed by Splunk Support.

Default value, auto, varies by the amount of physical RAM on the host

  • less than 2GB RAM = 67108864 (64MB) tsidx
  • 2GB to 8GB RAM = 134217728 (128MB) tsidx
  • more than 8GB RAM = 268435456 (256MB) tsidx

Values other than "auto" must be 16MB-1GB. Highest legal value (of the numerical part) is 4294967295

You can specify the value using a size suffix: "16777216" or "16MB" are equivalent.

maxTimeUnreplicatedNoAcks Number 300 Upper limit, in seconds, on how long an event can sit in raw slice. Applies only if replication is enabled for this index. Otherwise ignored.

If there are any acknowledged events sharing this raw slice, this paramater does not apply. In this case, maxTimeUnreplicatedWithAcks applies.

Highest legal value is 2147483647. To disable this parameter, set to 0.

Note: this is an advanced parameter. Understand the consequences before changing

maxTimeUnreplicatedWithAcks Number 60 Upper limit, in seconds, on how long events can sit unacknowledged in a raw slice. Applies only if you have enabled acks on forwarders and have replication enabled (with clustering).

Note: This is an advanced parameter. Make sure you understand the settings on all forwarders before changing this. This number should not exceed ack timeout configured on any forwarder, and should actually be set to at most half of the minimum value of that timeout. You can find this setting in outputs.conf readTimeout setting under the tcpout stanza.

To disable, set to 0, but this is NOT recommended. Highest legal value is 2147483647.

repFactor String 0 Value is either a non-negative number or "auto." This parameter only applies to Splunk clustering slaves.

auto: Use the value as configured with the master.

0: Specify zero to turn off replication for this index.

For information on configuring clusters, see Configure clusters in the Splunk Managing Indexing and Clusters manual.



POST data/inputs/monitor
POST data/inputs/monitor/{name}

The following parameter is new in Splunk 5.0.

Name Type Required Default Description
disabled Boolean Indicates if input monitoring is disabled.


POST data/inputs/win-perfmon
POST data/inputs/win-perfmon/{name}

The following parameters are new in Splunk 5.0.

Name Type Required Default Description
source String The value to populate in the source field for events from this data input. The same source should not be used for multiple events.
sourcetype String The value to populate in the sourcetype field for incoming events.


The following parameter, available in Splunk 4.3, is not available in Splunk 5.0.

disabled


POST data/outputs/tcp/group
POST data/outputs/tcp/group/{name}

The following parameter, available in Splunk 4.3, is not available in Splunk 5.0.

autoLB

In Splunk 4.3 you could use the autoLB parameter to specify automatic load balancing or round-robin load balancing. In Splunk 5.0, only automatic load balancing is available. If you previously specified round-robin load balancing in 4.3, it automatically converts to automatic load balancing.


POST data/outputs/tcp/server
POST data/outputs/tcp/server/{name}

The following parameters, available in Splunk 4.3, are not available in Splunk 5.0.

backoffAtStartup
initialBackoff
maxBackoff
maxNumberOfRetriesAtHighestBackoff

These parameters supported multi-casting, a feature that is no longer available in Splunk 5.0.


GET licenser/slaves
GET licenser/slaves/{name}

The following parameters, available in Splunk 4.3, are not available in Splunk 5.0.

poolid
stackid

These parameters were mistakenly introduced in an earlier version, and are non-functional. They have been removed for Splunk 5.0.


POST saved/searches
POST saved/searches/{name}

The following parameters are new in Splunk 5.0.


Name Type Required Default Description
action.email.reportCIDFontList Enum Space-separated list. Specifies the set (and load order) of CID fonts for handling Simplified Chinese(gb), Traditional Chinese(cns), Japanese(jp), and Korean(kor) in Integrated PDF Rendering.

If multiple fonts provide a glyph for a given character code, the glyph from the first font specified in the list is used.

To skip loading any CID fonts, specify the empty string.

Defaults to "gb cns jp kor"

action.email.reportIncludeSplunkLogo Boolean Indicates whether to include the Splunk logo with the report.
auto_summarize.max_summary_ratio Number 0.1 The maximum ratio of summary_size/bucket_size, which specifies when to stop summarization and deem it unhelpful for a bucket.

Note: The test is only performed if the summary size is larger than auto_summarize.max_summary_size.


POST saved/searches/{name}

The behavior of the following parameter has changed in Splunk 5.0

search (No longer a required parameter for this endpoint.)


POST search/distributed/config/{name}

The following parameters, available in Splunk 4.3, are not available in Splunk 5.0.

autoAddServers
blacklistNames
blacklistURLs
heartbeatFrequency
hertbeatMcastAddr
heartbeatPort
skipOurselves
ttl


GET search/distributed/peers
GET search/distributed/peers/{name}

The following parameter, available in Splunk 4.3, is not available in Splunk 5.0.

discoveredPeersOnly

This parameter supported multi-casting, a feature that is no longer available in Splunk 5.0.


GET search/jobs/export

The following parameters are new in Splunk 5.0.


Name Type Required Default Description
index_earliest String Specify a time string. Sets the earliest (inclusive), respectively, time bounds for the search, based on the index time.

The time string can be either a UTC time (with fractional seconds), a relative time specifier (to now) or a formatted time string.

index_latest String Specify a time string. Sets the latest (inclusive), respectively, time bounds for the search, based on the index time.

The time string can be either a UTC time (with fractional seconds), a relative time specifier (to now) or a formatted time string.


POST search/jobs

The following parameters are new in Splunk 5.0.


Name Type Required Default Description
index_earliest String Specify a time string. Sets the earliest (inclusive), respectively, time bounds for the search, based on the index time bounds.

The time string can be either a UTC time (with fractional seconds), a relative time specifier (to now) or a formatted time string. (Also see comment for the search_mode variable.)

index_latest String Specify a time string. Sets the latest (exclusive), respectively, time bounds for the search, based on the index time bounds.

The time string can be either a UTC time (with fractional seconds), a relative time specifier (to now) or a formatted time string.

Compare to latest_time parameter. Also see comment for the search_mode variable.


GET search/jobs/{search_id}/summary

The following parameter is new in Splunk 5.0.

Name Type Required Default Description
histogram Boolean false Indicates whether to add hitsogram data to the summary output.

Endpoints introduced with Splunk 5.0

The following endpoints are new, beginning with Splunk 5.0:

Cluster endpoints

cluster/config
cluster/config/{name}
cluster/master/buckets
cluster/master/buckets/{name}
cluster/master/peers
cluster/master/peers/{name}
cluster/master/generation
cluster/master/generation/{name}
cluster/master/info
cluster/master/info/{name}
cluster/searchhead/generation
cluster/searchhead/generation/{name}
cluster/slave/buckets
cluster/slave/buckets/{name}
cluster/slave/info
cluster/slave/info/{name}


Indexes

DELETE data/indexes/{name}


Search

saved/searches/{name}/reschedule
scheduled/views/{name}/reschedule
Retrieved from "http://docs.splunk.com/Documentation/Splunk/5.0.2/RESTAPI/RESTcontents"

This documentation applies to the following versions of Splunk: 5.0 , 5.0.1 , 5.0.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!