Skip to main content
Splunk® Enterprise

REST API Reference Manual

Splunk® Enterprise
7.0.13
Splunk Enterprise version 7.0 is no longer supported as of October 23, 2019. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see How to upgrade Splunk Enterprise.
This documentation does not apply to the most recent version of Splunk® Enterprise. For documentation on the most recent version, go to the latest release.

Cluster endpoint descriptions

Manage master and peer cluster nodes in Splunk Enterprise.

Usage details

Review ACL information for an endpoint

To check Access Control List (ACL) properties for an endpoint, append /acl to the path. For more information see Access Control List in the REST API User Manual.

Authentication and Authorization

Username and password authentication is required for access to endpoints and REST operations.

Splunk users must have role and/or capability-based authorization to use REST endpoints. Users with an administrative role, such as admin, can access authorization information in Splunk Web. To view the roles assigned to a user, select Settings > Access controls and click Users. To determine the capabilities assigned to a role, select Settings > Access controls and click Roles.

App and user context

Typically, knowledge objects, such as saved searches or event types, have an app/user context that is the namespace. For more information about specifying a namespace, see Namespace in the REST API User Manual.

Splunk Cloud limitations

If you have a managed Splunk Cloud deployment with search head clustering and index clustering, the REST API supports access to the search head only. You can use the REST API to interact with the search head in your deployment. Using the REST API to access any other cluster member nodes is not supported. For example, index cluster management endpoints are not applicable to Splunk Cloud deployments.

Authorized users can access and configure other cluster members, including indexer, cluster master, and license master nodes, in the Splunk Cloud manager user interface. 


cluster/config

https://<host>:<mPort>/services/cluster/config

Access cluster node configuration details.


GET

Expand

List cluster node configuration.


cluster/config/config

https://<host>:<mPort>/services/cluster/config/config

Manage cluster node configuration details.


GET

List cluster node configuration.

This operation works identically to the GET on cluster/config.


POST

Expand

Manage configuration details.


cluster/master/buckets

https://<host>:<mPort>/services/cluster/master/buckets

Provides bucket configuration information for a cluster master node.


GET

Expand

List cluster master node bucket configuration.


cluster/master/buckets/{name}

https://<host>:<mPort>/services/cluster/master/buckets/{name}

Access bucket configuration information.


GET

Expand

List bucket configuration information.


cluster/master/buckets/{bucket_id}/fix

https://<host>:<mPort>/services/cluster/master/buckets/{bucket_id}/fix

Add the specified bucket to the fix list.

For more information, see Bucket-fixing scenarios in Managing Indexers and Clusters of Indexers.

Authentication and Authorization
Requires the admin role or indexes_edit capability.


POST

Expand

Add this bucket to the fix list.


cluster/master/buckets/{bucket_id}/freeze

https://<host>:<mPort>/services/cluster/master/buckets/{bucket_id}/freeze

Set the bucket's state to frozen. The frozen state may not persist after a cluster master restart unless one of the peers has set the frozen state. A POST to this endpoint does not set the bucket's state to frozen on peers.

Note: Use this endpoint with caution. It is recommended to test the endpoint in a test cluster prior to use on an actual bucket.

For more information, see How the cluster handles frozen buckets in Managing Indexers and Clusters of Indexers.

Authentication and Authorization

Requires the admin role or indexes_edit capability.


POST

Expand

Set this bucket's state to frozen.



cluster/master/buckets/{bucket_id}/remove_all

https://<host>:<mPort>/services/cluster/master/buckets/{bucket_id}/remove_all

Delete all copies of the specified bucket.

Caution: Using this endpoint will cause irreversible data loss. It is recommended to test the endpoint on a test cluster prior to use on an actual bucket.

Authentication and Authorization
Requires the admin role or indexes_edit capability.


POST

Expand

Delete all copies of the specified bucket.



cluster/master/buckets/{bucket_id}/remove_from_peer

https://<host>:<mPort>/services/cluster/master/buckets/{bucket_id}/remove_from_peer

Deletes the copy of this bucket from specified peer.

If the request causes the cluster to lose its complete state, the cluster will engage in fixup activities. This may result in another copy of the same bucket appearing on this peer. If, however, the specified bucket is frozen, the cluster does not attempt any fixup activities.

Caution: Using this endpoint will cause irreversible data loss. It is recommended to test the endpoint on a test-cluster prior to use on an actual bucket.


Authentication and Authorization
Requires the admin role or indexes_edit capability.


POST

Expand

Delete this bucket from specified peer. Set bucket state to frozen



cluster/master/control/control/prune_index

https://<host>:<mPort>/services/cluster/master/control/control/prune_index

Clean up excess bucket copies across an index.

For more information, see Remove extra bucket copies in Managing Indexers and Clusters of Indexers.


POST

Expand

Clean up excess bucket copies across an index.

cluster/master/control/control/rebalance_primaries

https://<host>:<mPort>/services/cluster/master/control/control/rebalance_primaries

Rebalance primary bucket copies across peers. For more information, see Rebalance the indexer cluster primary buckets in Managing Indexers and Clusters of Indexers.


POST

Expand

Rebalance primary buckets across all peers of this master.


cluster/master/control/control/remove_peers

https://<host>:<mPort>/services/cluster/master/control/control/remove_peers

Remove one or more peers.

See also
cluster/master/peers


POST

Expand

Remove one or more peers.


cluster/master/control/control/resync_bucket_from_peer

https://<host>:<mPort>/services/cluster/master/control/control/resync_bucket_from_peer

This endpoint resets the state of a specified bucket based on the current state of the bucket at a peer.


POST

Expand

Reset bucket state based on the current state of the bucket at a peer.


cluster/master/control/control/roll-hot-buckets

https://<host>:<mPort>/services/cluster/master/control/control/roll-hot-buckets

This endpoint forces a specified bucket in an indexer cluster to roll from hot to warm. Pass the bucket id (bid) to the master node. The master instructs the origin peer for that bucket to roll its copy. In turn, the origin peer tells all the replicating peers to roll their copies

You might discover a bucket that is stuck in fixup and needs to be rolled using logs, Splunk Web, or either of the following two endpoints.


Authorization and authentication
This endpoint requires the admin role for use.


POST

Expand

Force a bucket to roll from hot to warm.



cluster/master/control/default/apply

https://<host>:<mPort>/services/cluster/master/control/default/apply

Pushes a bundle.


POST

Expand

Push a bundle.


cluster/master/control/default/cancel_bundle_push

https://<host>:<mPort>/services/cluster/master/control/default/cancel_bundle_push

Cancels and resets the bundle push operation. Use this endpoint when the cluster master does not receive a validation response from the cluster peer due to an error. For more information, see Configuration bundle issues.


POST

Expand

Cancel and reset the bundle push operation.


cluster/master/control/default/rollback

https://<host>:<mPort>/services/cluster/master/control/default/rollback

Roll a bundle back to the previously active bundle.


POST

Expand

Roll back a bundle.


cluster/master/control/default/validate_bundle

https://<host>:<mPort>/services/cluster/master/control/default/validate_bundle

Tests if the bundle in etc/master-apps passes validation. Optionally, tests if the bundle will trigger an indexer restart.


POST

Expand

Validate a bundle.

cluster/master/fixup

https://<host>:<mPort>/services/cluster/master/fixup

Access a list of buckets on a specific fixup priority level. Bucket fixups are processed in order of priority level. See Request parameters below for priority level details.

When you access a particular fixup level, buckets may appear in it even though they do not need fixup at this level. Initially, each bucket requiring fixup is added to all levels, even though it might only require processing in a subset of all levels. As the bucket is processed through a level, it is deleted from that level.


GET

Expand

List buckets on the specified fixup level.



cluster/master/generation

https://<host>:<mPort>/services/cluster/master/generation

Access current generation cluster master information and create a cluster generation.


GET

Expand

List peer nodes participating in the current generation for this master.


POST

Expand

Create a cluster generation.


cluster/master/generation/{name}

https://<host>:<mPort>/services/cluster/master/generation/{name}

Access information about a peer node participating in the current generation for the specified search head GUID.


GET

Expand

List peer node information of the specified search head GUID.


POST

Expand

Create a new generation for the specified search head GUID.


cluster/master/indexes

https://<host>:<mPort>/services/cluster/master/indexes

Access cluster index information.


GET

Expand

List cluster indices.


cluster/master/indexes/{name}

https://<host>:<mPort>/services/cluster/master/indexes/{name}

Access specific cluster index information.


GET

Expand

List {name} index information.


cluster/master/info

https://<host>:<mPort>/services/cluster/master/info

Access information about cluster master node.


GET

Expand

List cluster master node details.


cluster/master/peers

https://<host>:<mPort>/services/cluster/master/peers

Access cluster master peers.

See also
cluster/master/control/control/remove_peers


GET

Expand

List cluster master peers.


cluster/master/peers/{name}

https://<host>:<mPort>/services/cluster/master/peers/{name}

Access specified peer.


GET

Expand

Get {name} peer information.


cluster/master/sites

https://<host>:<mPort>/services/cluster/master/sites

Access cluster site information.


GET

Expand

List available cluster sites.


cluster/master/sites/{name}

https://<host>:<mPort>/services/cluster/master/sites/{name}

Access specific cluster site information.


GET

Expand

List the {name} cluster site information.



cluster/searchhead/generation

https://<host>:<mPort>/services/cluster/searchhead/generation

Access peer information in a cluster searchhead.


GET

Expand

List peers available to a cluster searchhead.


cluster/searchhead/generation/{name}

https://<host>:<mPort>/services/cluster/searchhead/generation/{name}

Access peer of the master URI.


GET

Expand

Get {name} searchhead generation ID and generation peers.


cluster/searchhead/searchheadconfig

https://<host>:<mPort>/services/cluster/searchhead/searchheadconfig

Access cluster searchhead node configuration.


GET

Expand

List this cluster search head node configuration.


POST

Expand

Configure this server as a cluster searchhead node.



cluster/searchhead/searchheadconfig/{name}

https://<host>:<mPort>/services/cluster/searchhead/searchheadconfig/{name}

Manage node in a cluster.


DELETE

Expand

Remove node from cluster.


GET

Expand

List cluster search head node configuration.


POST

Expand

Update cluster search head node configuration.


cluster/slave/buckets

https://<host>:<mPort>/services/cluster/slave/buckets

Access cluster peers bucket configuration.


GET

Expand

List cluster peers bucket configuration.


cluster/slave/buckets/{name}

https://<host>:<mPort>/services/cluster/slave/buckets/{name}

Manage peer buckets.


DELETE

Expand

Remove specified bucket from peer node.


GET

Expand

List peer specified bucket information.


cluster/slave/control/control/re-add-peer

https://<host>:<mPort>/services/cluster/slave/control/control/re-add-peer

Set the peer to re-add itself to the master. This syncs the peer's state, including its in-memory bucket state, to the master. By default, this resets the peer's primary bucket copies and the master reassigns them across the cluster. To keep the peer's existing primary bucket copies, use the optional clearMasks=false parameter.

This endpoint can be useful when the master and the peer have a state mismatch, for example when bucket information is not in sync between them.


POST

Expand

Re-add the cluster indexer to the cluster master.


cluster/slave/control/control/set_detention_override

https://<host>:<mPort>/services/cluster/slave/control/control/set_manual_detention


Deprecated. Use /set_manual_detention to manage peer node manual detention mode.


cluster/slave/control/control/set_manual_detention

https://<host>:<mPort>/services/cluster/slave/control/control/set_manual_detention

If you have Splunk Enterprise, you can use this endpoint to put the peer node in manual detention mode or take the peer out of this mode. In manual detention, the peer does not serve as a replication target. Detention helps slow the growth of disk usage on the peer.

Note:

  • This endpoint replaces the /set_detention_override endpoint.
  • Starting with Splunk Enterprise software version 6.5, manual detention persists through restarts.
  • For more information, see Put a peer in detention in Managing Indexers and Clusters of Indexers.


POST

Expand

Adjust cluster peer detention mode.


cluster/slave/info

https://<host>:<mPort>/services/cluster/slave/info

Access cluster peer node information.


GET

Expand

List peer information.


replication/configuration/health

https://<host>:<mPort>/services/replication/configuration/health

Access configuration replication health statistics for a search head cluster.

GET

Expand

Access the configuration replication health statistics for a search head cluster.


shcluster/captain/artifacts

https://<host>:<mPort>/services/shcluster/captain/artifacts

Provides list of artifacts and replicas currently managed by the captain across a searchhead cluster.

This endpoint can only be accessed on the captain. The response lists all of the artifacts that are currently managed by the captain across the searchhead cluster, present on the various members.

An artifact in search head clustering is a managed search directory. Currently, only scheduled search results directories are managed and replicated according to replication policy.

Note: Ad hoc searches are not considered artifacts and are not listed.


GET

Expand

Lists searchhead cluster artifacts and replicas.


shcluster/captain/artifacts/{name}

https://<host>:<mPort>/services/shcluster/captain/artifacts/{name}

Get artifact information for a specific artifact.


GET

Expand

Get artifact information, size, replicas and earliest service time.




shcluster/captain/info

https://<host>:<mPort>/services/shcluster/captain/info

Access information about searchhead cluster captain node.


GET

Expand

List searchhead cluster captain node details.



shcluster/captain/jobs

https://<host>:<mPort>/services/shcluster/captain/jobs

List running and recently finished jobs for all cluster members.


GET

Expand

List running and recently finished jobs for this cluster.



shcluster/captain/jobs/{name}

https://<host>:<mPort>/services/shcluster/captain/jobs/{name}


GET

Expand

Get running and recently finished jobs for {name} cluster.


shcluster/captain/members

https://<host>:<mPort>/services/shcluster/captain/members

Lists the search head cluster members.


GET

Expand

List cluster members.


shcluster/captain/members/{name}

https://<host>:<mPort>/services/shcluster/captain/members/{name}

Get information about the {name} searchhead cluster member.


GET

Expand

Get information about the {name} searchhead cluster member.


shcluster/config

https://<host>:<mPort>/services/shcluster/config

List search head cluster node configuration.


GET

Expand

List the search head cluster node configuration.


shcluster/member/artifacts

https://<host>:<mPort>/services/shcluster/member/artifacts

Manage searchhead cluster member artifact configuration.


GET

Expand

List searchhead cluster members artifact configuration.


shcluster/member/artifacts/{name}

https://<host>:<mPort>/services/shcluster/member/artifacts/{name}

Get {name} member artifact configuration.


GET

Expand

List {name} member artifact information.


shcluster/member/consensus

https://<host>:<mPort>/services/shcluster/member/consensus

Get latest cluster configuration from the raft consensus protocol.


GET

Expand

Get latest cluster configuration from the raft consensus protocol.


shcluster/member/info

https://<host>:<mPort>/services/shcluster/member/info

Access searchhead cluster member node information.


GET

Expand

List member information.


Last modified on 16 January, 2019
Application endpoint descriptions   Configuration endpoint descriptions

This documentation applies to the following versions of Splunk® Enterprise: 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13


Was this topic useful?







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