Managing knowledge objects
This section shows some typical use cases for managing objects in the REST API. Use these examples to learn how to perform operations such as moving an object to a different app or changing the permissions of an object.
You can also use the servicesNS endpoints to access resources within a user/app context called the namespace. For more information about using namespaces, see Namespace in the REST API User Manual.
Create a new object for a specific context
Create a saved search for the user Alice that is available from the app, myapp. This saved search is private to Alice.
curl -k -u alice:pass https://localhost:8089/servicesNS/alice/myapp/saved/searches/ \ -d name=mysearch \ -d search=*
Edit an object
Change the above search created for Alice.
Because this search is private to Alice, she can edit the search.
curl -k -u alice:pass https://localhost:8089/servicesNS/alice/myapp/saved/searches/mysearch \ -d search="index=mai*"
In general, use the REST handler associated with a knowledge object to programmatically modify it. The search macros and transactions types of knowledge objects, however, do not have an associated REST handler. For these types of knowledge objects, modify them by manipulating the configuration file directly with the /configs
endpoint. For more information about the /configs
endpoint, see Configuration endpoint descriptions in the REST API Reference Manual.
In either case, modify permissions for knowledge objects with the Access Control List (ACL) endpoints. For more information about the ACL endpoints, see Access Control List in the REST API User Manual.
Consult the following table to determine which method to use for each type of knowledge object. For detailed descriptions of each endpoint, see the REST API Reference Manual.
Knowledge object type | Modification method | REST API endpoint |
---|---|---|
Data models | REST handler | /datamodel/model/{name} |
Event types | REST handler | /saved/eventtypes/{name} |
Field extractions | REST handler | /data/transforms/extractions/ or /data/props/extractions/{name} |
Fields | REST handler | /search/fields/{name} |
Lookups | REST handler | /data/props/lookups/{name} |
Navigation | REST handler | /services/directory/{name} |
Panels | REST handler | /data/ui/panels |
Saved searches | REST handler | /saved/searches/{name} |
Search macros | configuration file | /services/configs/conf-macros/{name} |
Tags | REST handler | /search/tags/ |
Transactions | configuration file | /services/configs/conf-transactiontypes/{name} |
Views | REST handler | /data/ui/views |
Modify an object's permissions with the REST handler
For example, you can make Alice's saved search, mysearch, available through the app, myapp, by using the saved/searches/mysearch REST handler. The following command grants all users permissions to read the saved search.
curl -k -u admin:pass https://localhost:8089/servicesNS/alice/myapp/saved/searches/mysearch/acl \ -d perms.read=* \ -d owner=alice \ -d sharing=app
Edit the search at the shared location. Because the search is now a shared resource, use <nobody> for the <user> context.
curl -k -u alice:pass https://localhost:8089/servicesNS/nobody/myapp/saved/searches/mysearch \ -d search="index=main"
Modify an object's permissions by editing configuration files
Similarly, you can make Bob's macro, mymacro, available globally by editing the macros configuration file. The following command shares mymacro globally and grants write permissions for admin and power roles.
curl -k -u bob:pass https://localhost:8089/services/configs/conf-macros/mymacro/acl -d "sharing=global&owner=nobody"
After you run the command, the macro is available in the main search app.
The following command modifies permissions so that mymacro can still be read by everyone, but is owned and can be written only by users with the admin role.
curl -k -u bob:pass https://localhost:8089/services/configs/conf-macros/mymacro/acl -d "perms.read=*&perms.write=admin&owner=admin&sharing=global"
Move an object to a different app
The saved search that was previously available to all in the context of myapp is now only available in the context of otherapp.
curl -k -u admin:pass https://localhost:8089/servicesNS/nobody/myapp/saved/searches/mysearch/move \ -d user=nobody \ -d app=otherapp
Access objects available in all user/app contexts
Using wildcards, access all saved searches that you have permission to view.
For an admin user, this includes other user's private saved searches.
For a non-admin user, you retrieve only saved searches you have permission to view.
curl -k -u admin:pass https://localhost:8089/servicesNS/-/-/saved/searches curl -k -u alice:pw https://localhost:8089/servicesNS/-/-/saved/searches
Access requirements and limitations for the Splunk Cloud Platform REST API | Creating searches using the REST API |
This documentation applies to the following versions of Splunk Cloud Platform™: 8.2.2112, 8.2.2201, 8.2.2202, 8.2.2203, 9.0.2205, 9.0.2208, 9.0.2209, 9.0.2303, 9.0.2305, 9.1.2308, 9.1.2312, 9.2.2403, 9.2.2406 (latest FedRAMP release)
Feedback submitted, thanks!