OpenAPI-based Configuration Management endpoint descriptions

Understand the RESTful Configuration Management API for the Splunk platform. You can also download the Config Management OpenAPI contract.

For background on the Splunk configuration file system, see:

• About configuration files
• Configuration file directories
• Configuration file structure

Read operations

Configuration scoping

The configuration scope that the API caller applies for each API endpoint depends on two factors:

• The REST path prefix — /services or /servicesNS/{user}/{app} — from the existing REST API
• The view query parameter

App-scoped views (view=app-local | app-default | app-merged)

For app-scoped views, the path prefix maps to a single folder on disk. The view parameter then selects which subdirectory (local/, default/, or both) the system reads within that folder.

app-local — Reads only the local/ subdirectory:

app-default — Reads the default/ subdirectory only:

app-merged — Reads and merges both local/ and default/, with local/ values taking priority:

Materialized view (view=materialized)

The materialized view merges applicable configuration layers (user, app, exported apps, and system) following standard precedence rules and returns the fully resolved value.

The exact layering depends on the configuration context set by the REST prefix (app/user vs global context), see: Configuration file precedence.

Paths listed highest to lowest precedence:

Filtering, sorting, and pagination

The following table provides the per-endpoint supportability matrix for filtering, pagination, and sorting.

Pagination

Step through large result sets:

• count (integer): Maximum number of results to return per page. 0 or omitted uses the default page size of 30. Maximum allowed value is 100,000.
• offset (integer): Number of results to skip. Combine with count to page through results. For example: count=10&offset=0 returns page 1, count=10&offset=10 returns page 2, and so on.
• Default: Returns up to 30 results starting from offset 0.

Sorting

Control result order:

• sort_dir (string): asc (ascending) or desc (descending). Sorts alphabetically by entity name at each level (conf type name, stanza name, or setting name). No support for custom sort fields.
• Default: asc.

Filtering

Query parameter filtering

Filters the returned list of conf type names through URL query parameters:

• filter (string): The pattern to match against conf type names.
• mode (string, default exact): exact for literal match; regex for regular expression match. Regex mode matches any substring of the name. Use ^ and $ anchors for full-string matching.
• Default: Does not filter queries; returns all conf types.

Request body filtering

Filters passed in the request body (NameFilter) to avoid URI length limits. When you supply multiple filters, the method returns any result that matches at least one filter. Accepts exact for literal match and regex for regular expression match. Regex mode matches any substring of the name. Use ^ and $ anchors for full-string matching.

Filters by the primary resource identifier:

• Stanza name for conf type reads.
• Setting name for stanza reads.
• Default: Does not filter request body names; returns all results.

Write operations

Stanza- and setting-level write operations use collection-level endpoints with the resource name in the request body. This avoids URI length limitations as Splunk configuration stanza/setting names can exceed 2 KB when URL-encoded.

Write scope

All write operations target the local/ directory only. The destination folder is determined by the REST path prefix:

Atomicity guarantees

• Stanza level: ATOMIC — Method writes all settings in a stanza atomically (all writes either succeed or fail completely).
• Setting level: ATOMIC — single setting written atomically.

Default stanza

• Use default as the stanza name to address the default stanza.
• Settings that appear before any stanza header in a conf file, or under an explicit [default] header, are both accessed through the default name.
• Not all conf files support a default stanza (for example, collections.conf, tags.conf, app.conf). Write operations to those files return a 404 for default.
• Flat conf files with no stanza concept (for example, source-classifier.conf, splunk-launch.conf) expose all settings under the default stanza.

Write semantics

Write operations that are not specifically for deleting content apply the following rules before writing to persistent storage in the local/ subdirectory:

• Writes target local/ only: The system determines the local/ destination using the REST path prefix. See the Write Scope table in this topic for the mapping of REST path prefixes to filesystem destinations.
• Diff suppression: To prevent redundant local overrides, the system does not write settings changes to the local/ directory in cases where the updated setting value matches the present value for that setting.
• Empty value suppression: The system does not write settings changes to the local/ directory in cases where there is no existing value for a setting and the proposed updated value is an empty string.
• API semantics scoped to local/: The system scopes all API semantics (for example, the target resource, existence checks, HTTP status codes, and response body) to reflect the local/ layer only. The response returns the post-operation state of local/ for the affected stanza or setting.

Deployment scope

Write operations in this contract are designed for non-clustered Splunk platform deployments. They operate against the local filesystem layer of the node that receives the request directly and have no built-in awareness of cluster topology.

In environments with an existing replication mechanism, such as Search Head Cluster replication, those mechanisms continue to apply changes independently. This API does not interfere with or bypass them. Changes that callers make through this API are subject to the same replication behavior as any direct write to local/.

For details on how configuration changes propagate in a Search Head Cluster, see: How configuration changes propagate across the search head cluster.