Skip to main content
Splunk® Enterprise

REST API Reference Manual

Splunk® Enterprise
9.2.0
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 indexer clusters and search head clusters in Splunk Enterprise.

To distinguish indexer cluster endpoints from search cluster endpoints, note:

The values manager and peer replace the prior values of master and slave. The prior values are currently still supported, but they will be removed from the product in a future release.

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 Platform limitations

As a Splunk Cloud Platform user, you are restricted to interacting with the search tier only with the REST API. Cluster endpoints are generally not accessible in Splunk Cloud Platform.

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

See Access requirements and limitations for the Splunk Cloud Platform REST API in the the REST API Tutorials manual for more information.


Indexer cluster endpoints

The endpoints in this section pertain to indexer clusters.

All endpoints that contain cluster in their URIs pertain to indexer clusters. In this section, if a URI contains the term search head, it refers to search head nodes in the indexer cluster. The term peer node refers to peer nodes in the indexer cluster. For more information about indexer cluster architecture, see The basics of indexer cluster architecture and Search head configuration overview in the Managing Indexers and Clusters of Indexers manual.

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/manager/buckets

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

Provides bucket configuration information for a cluster manager node.


GET

Expand

List cluster manager node bucket configuration.


cluster/manager/buckets/{name}

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

Access bucket configuration information.


GET

Expand

List bucket configuration information.


cluster/manager/buckets/{bucket_id}/fix

https://<host>:<mPort>/services/cluster/manager/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/manager/buckets/{bucket_id}/fix_corrupt_bucket

https://<host>:<mPort>/services/cluster/manager/buckets/{bucket_id}/fix_corrupt_bucket

Trigger a corruption fixup of a clustered non-SmartStore-enabled bucket.

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

Authentication and Authorization
Requires the admin role or edit_indexer_cluster capability.


POST

Expand

Trigger a corruption fixup for this bucket.


cluster/manager/buckets/{bucket_id}/freeze

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

Set the bucket's state to frozen. The frozen state may not persist after a cluster manager 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/manager/buckets/{bucket_id}/remove_all

https://<host>:<mPort>/services/cluster/manager/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/manager/buckets/{bucket_id}/remove_from_peer

https://<host>:<mPort>/services/cluster/manager/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/manager/control/control/prune_index

https://<host>:<mPort>/services/cluster/manager/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/manager/control/control/rebalance_primaries

https://<host>:<mPort>/services/cluster/manager/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 manager.


cluster/manager/control/control/remove_peers

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

Remove one or more peers.

See also
cluster/manager/peers


POST

Expand

Remove one or more peers.


cluster/manager/control/control/resync_bucket_from_peer

https://<host>:<mPort>/services/cluster/manager/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/manager/control/control/roll-hot-buckets

https://<host>:<mPort>/services/cluster/manager/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 manager node. The manager 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/manager/control/control/rolling_upgrade_finalize

https://<host>:<mPort>/services/cluster/manager/control/control/rolling_upgrade_finalize

Finalizes an indexer cluster rolling upgrade.


POST

Expand

Finalizes an indexer cluster rolling upgrade.


cluster/manager/control/control/rolling_upgrade_init

https://<host>:<mPort>/services/cluster/manager/control/control/rolling_upgrade_init

Initializes an indexer cluster rolling upgrade.


POST

Expand

Initializes an indexer cluster rolling upgrade.


cluster/manager/control/default/abort_restart

https://<host>:<mPort>/services/cluster/manager/control/default/abort_restart

Aborts an ongoing restart of an indexer cluster.

Authentication and Authorization

Requires the admin role or edit_indexer_cluster capability.


POST

Expand

Abort an ongoing restart of an indexer cluster.


cluster/manager/control/default/apply

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

Pushes a bundle.


POST

Expand

Push a bundle.


cluster/manager/control/default/cancel_bundle_push

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

Cancels and resets the bundle push operation. Use this endpoint when the cluster manager 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/manager/control/default/maintenance

https://<host>:<mPort>/services/cluster/manager/control/default/maintenance

Put the cluster manager into maintenance mode.


POST

Expand

Toggle maintenance mode.


cluster/manager/control/default/rollback

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

Roll a bundle back to the previously active bundle.


POST

Expand

Roll back a bundle.


cluster/manager/control/default/validate_bundle

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

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


POST

Expand

Validate a bundle.


cluster/manager/fixup

https://<host>:<mPort>/services/cluster/manager/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/manager/generation

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

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


GET

Expand

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


POST

Expand

Create a cluster generation.


cluster/manager/generation/{name}

https://<host>:<mPort>/services/cluster/manager/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/manager/ha_active_status

https://<host>:<mPort>/services/cluster/manager/ha_active_status

Used by the load balancers to check the high availability mode of a given cluster manager.

The active cluster manager will return "HTTP 200", denoting "healthy", and a startup or standby cluster manager will return "HTTP 503".

Authentication and authorization
This endpoint is unauthenticated because some load balancers don't support authentication on a health check endpoint.

GET

Expand
Checks the high availability mode of a given cluster manager.

cluster/manager/health

https://<host>:<mPort>/services/cluster/manager/health

Performs health checks to determine the cluster health and search impact, prior to a rolling upgrade of the indexer cluster.

Authentication and Authorization

Requires the admin role or list_indexer_cluster capability.


GET

Expand

Get indexer cluster health check results.


cluster/manager/indexes

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

Access cluster index information.


GET

Expand

List cluster indices.


cluster/manager/indexes/{name}

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

Access specific cluster index information.


GET

Expand

List {name} index information.


cluster/manager/info

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

Access information about cluster manager node.


GET

Expand

List cluster manager node details.


cluster/manager/peers

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

Access cluster manager peers.

See also
cluster/manager/control/control/remove_peers


GET

Expand

List cluster manager peers.


cluster/manager/peers/{name}

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

Access specified peer.


GET

Expand

Get {name} peer information.


cluster/manager/redundancy

https://<host>:<mPort>/services/cluster/manager/redundancy

Display the details of all cluster managers participating in cluster manager redundancy, and switch the HA state of the cluster managers.

Authentication and authorization
The GET on this endpoint needs the capability list_indexer_cluster, and the POST on this endpoint needs the capability edit_indexer_cluster.

GET

Expand

Display the details of all cluster managers participating in cluster manager redundancy.

POST

Expand

Switch the high availability state of the cluster managers.


cluster/manager/sites

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

Access cluster site information.


GET

Expand

List available cluster sites.


cluster/manager/sites/{name}

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

Access specific cluster site information.


GET

Expand

List the {name} cluster site information.


cluster/manager/status

https://<host>:<mPort>/services/cluster/manager/status

Endpoint to get the status of a rolling restart.


GET

Expand

Get the status of a rolling restart.


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 manager 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/peer/buckets

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

Access cluster peers bucket configuration.


GET

Expand

List cluster peers bucket configuration.


cluster/peer/buckets/{name}

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

Manage peer buckets.


DELETE

Expand

Remove specified bucket from peer node.


GET

Expand

List peer specified bucket information.


cluster/peer/control/control/decommission

https://<host>:<mPort>/services/cluster/peer/control/control/decommission

Endpoint to decommission an indexer cluster peer node.


POST

Expand

Decommission a peer node.


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

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

Set the peer to re-add itself to the manager. This syncs the peer's state, including its in-memory bucket state, to the manager. By default, this resets the peer's primary bucket copies and the manager 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 manager 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 manager.


cluster/peer/control/control/set_detention_override

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


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


cluster/peer/control/control/set_manual_detention

https://<host>:<mPort>/services/cluster/peer/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/peer/info

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

Access cluster peer node information.


GET

Expand

List peer information.


Search head cluster endpoints

The endpoints in this section pertain to search head clusters.

All endpoints contain shcluster in their URIs pertain to search head clusters. For more information about search head clustering architecture, see Search head clustering architecture in the Distributed Search manual.

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 artifacts that are currently resident on the set of search head cluster 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/control/default/restart

https://<host>:<mPort>/services/shcluster/captain/control/default/restart

Endpoint to initiate rolling restart of a search head cluster.


POST

Expand

Initiates rolling restart of a search head cluster


shcluster/captain/control/control/rotate-splunk-secret

https://<host>:<mPort>/services/shcluster/captain/control/control/rotate-splunk-secret

Rotates the splunk.secret file on all nodes of a search head cluster.

POST

Expand

Rotates the splunk.secret file on all nodes of a search head cluster.


shcluster/captain/control/control/upgrade-init

https://<host>:<mPort>/services/shcluster/captain/control/control/upgrade-init

Initializes a search head cluster rolling upgrade.


POST

Expand

Initializes a search head cluster rolling upgrade.


shcluster/captain/control/control/upgrade-finalize

https://<host>:<mPort>/services/shcluster/captain/control/control/upgrade-finalize

Finishes a search head cluster rolling upgrade.


POST

Expand

Finishes a search head cluster rolling upgrade.


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 search head cluster node configuration.


shcluster/config/config

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

Configure search head cluster members.


POST

Expand

Configure search head cluster members.


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/control/control/set_manual_detention

https://<host>:<mPort>//services/shcluster/member/control/control/set_manual_detention

Put the search head cluster member in manual detention mode or take the search head cluster member out of this mode. When a search head cluster member is in manual detention, it does not accept new search jobs, including both scheduled and ad-hoc searches. Existing search jobs run to completion. It also participates in cluster administration operations with the exception of artifact replication.


POST

Expand

Adjust search head manual detention mode.


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.


shcluster/status

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

Performs health checks to determine search head cluster health status, prior to a rolling upgrade or rolling restart.

Authentication and Authorization

Requires the admin role or list_search_head_clustering capability.


GET

Expand

Get search head cluster health status information .


upgrade/shc/recovery

https://<host>:<mPort>/services/upgrade/shc/recovery

Return search head cluster to ready state after automated rolling upgrade failure.


Authentication and Authorization
Requires admin role or another role containing these capabilties:

  • upgrade_splunk_shc
  • list_search_head_clustering
  • list_settings
  • use_remote_proxy


POST

Expand

Return SHC to ready state after automated rolling upgrade failure.


upgrade/shc/status

https://<host>:<mPort>/services/upgrade/shc/status

Check the status of an automated search head cluster rolling upgrade.


Authentication and Authorization
Requires admin role or another role containing these capabilities:

  • upgrade_splunk_shc
  • list_search_head_clustering
  • list_settings
  • use_remote_proxy


GET

Expand

Check the status of automated SHC rolling upgrade.


upgrade/shc/upgrade

https://<host>:<mPort>/services/upgrade/shc/upgrade

Initiate an automated rolling upgrade of a search head cluster.


Authentication and Authorization
Requires admin role or another role containing these capabilities:

  • upgrade_splunk_shc
  • list_search_head_clustering
  • list_settings
  • use_remote_proxy


POST

Expand

Initiate automated SHC rolling upgrade.


Last modified on 31 August, 2024
Application endpoint descriptions   Configuration endpoint descriptions

This documentation applies to the following versions of Splunk® Enterprise: 9.2.0, 9.2.1, 9.2.2, 9.2.3, 9.2.4, 9.3.0, 9.3.1, 9.3.2


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