Rudder API
Download OpenAPI specification: [openapi.yml](openapi.yml) Introduction Rudder exposes a REST API, enabling the user to interact with Rudder without using the…
Developer tools#openapi#developer-tools
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
Download OpenAPI specification: [openapi.yml](openapi.yml)
Introduction
Rudder exposes a REST API, enabling the user to interact with Rudder without using the webapp, for example in scripts or cronjobs.
Versioning
Each time the API is extended with new features (new functions, new parameters, new responses, ...), it will be assigned a new version number. This will allow you
to keep your existing scripts (based on previous behavior). Versions will always be integers (no 2.1 or 3.3, just 2, 3, 4, ...) or latest.
You can change the version of the API used by setting it either within the url or in a header:
- the URL: each URL is prefixed by its version id, like
/api/version/function.
# Version 10
curl -X GET -H "X-API-Token: yourToken" https://rudder.example.com/rudder/api/10/rules
# Latest
curl -X GET -H "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/rules
# Wrong (not an integer) => 404 not found
curl -X GET -H "X-API-Token: yourToken" https://rudder.example.com/rudder/api/3.14/rules- the HTTP headers. You can add the X-API-Version header to your request. The value needs to be an integer or
latest.
# Version 10
curl -X GET -H "X-API-Token: yourToken" -H "X-API-Version: 10" https://rudder.example.com/rudder/api/rules
# Wrong => Error response indicating which versions are available
curl -X GET -H "X-API-Token: yourToken" -H "X-API-Version: 3.14" https://rudder.example.com/rudder/api/rulesIn the future, we may declare some versions as deprecated, in order to remove them in a later version of Rudder, but we will never remove any versions without warning, or without a safe
period of time to allow migration from previous versions.
Existing versions
Version
Rudder versions it appeared in
Description
1
Never released (for internal use only)
Experimental version
2 to 10 (deprecated)
4.3 and before
These versions provided the core set of API features for rules, directives, nodes global parameters, change requests and compliance, rudder settings and system API
11
5.0
New system API (replacing old localhost v1 api): status, maintenance operations and server behavior
12
6.0 and 6.1
Node key management
13
6.2
Node status endpoint
System health check
System maintenance job to purge software [that endpoint was back-ported in 6.1]
14
7.0
Secret management
Directive tree
Improve techniques management
Demote a relay
15
7.1
Package updates in nodes
16
7.2
Create node API included from plugin
Configuration archive import/export
Response format
All responses from the API are in the JSON format.
{
"action": "The name of the called function",
"id": "The ID of the element you want, if relevant",
"result": "The result of your action: success or error",
"data": "Only present if this is a success and depends on the function, it's usually a JSON object",
"errorDetails": "Only present if this is an error, it contains the error message"
}- __Success__ responses are sent with the 200 HTTP (Success) code
- __Error__ responses are sent with a HTTP error code (mostly 5xx...)
HTTP method
Rudder's REST API is based on the usage of HTTP methods. We use them to indicate what action will be done by the request. Currently, we use four of them:
- GET: search or retrieve information (get rule details, get a group, ...)
- PUT: add new objects (create a directive, clone a Rule, ...)
- DELETE: remove objects (delete a node, delete a parameter, ...)
- POST: update existing objects (update a directive, reload a group, ...)
Parameters
General parameters
Some parameters are available for almost all API functions. They will be described in this section.
They must be part of the query and can't be submitted in a JSON form.
Available for all requests
Field
Type
Description
prettify
boolean optional
Determine if the answer should be prettified (human friendly) or not. We recommend using this for debugging purposes, but not for general script usage as this does add some unnecessary load on the server side.
Default value: false
Available for modification requests (PUT/POST/DELETE)
Field
Type
Description
reason
string optional or required
Set a message to explain the change. If you set the reason messages to be mandatory in the web interface, failing to supply this value will lead to an error.
Default value: ""
changeRequestName
string optional
Set the change request name, is used only if workflows are enabled. The default value depends on the…
Endpoints 134
API Info
- GETList all endoints
/infoList all endpoints and their version - GETGet information about one API endpoint
/info/details/:endpointNameGet the description and the list of supported version for one API endpoint - GETGet information on endpoint in a section
/info/:sectionIdGet all endpoints in the given section with their supported version.
Status
- GETCheck if Rudder is alive
/statusAn unauthenticated API to check if Rudder web application is up and running. Be careful: this API does not follow other Rudder's API convention: it is not…
Compliance
- GETGlobal compliance
/compliance?precision=0Get current global compliance of a Rudder server - GETCompliance details for all nodes
/compliance/nodes?level=4&precision=0Get current compliance of all the nodes of a Rudder server - GETCompliance details by node
/compliance/nodes/:nodeId?level=4&precision=0Get current compliance of a node of a Rudder server - GETCompliance details for all rules
/compliance/rules?level=4&precision=0Get current compliance of all the rules of a Rudder server - GETCompliance details by rule
/compliance/rules/:ruleId?level=4&precision=0Get current compliance of a rule of a Rudder server
Rules
- GETList all rules
/rulesList all rules - PUTCreate a rule
/rulesCreate a new rule. You can specify a source rule to clone it. - PUTCreate a rule category
/rules/categoriesCreate a new rule category - GETGet rule category details
/rules/categories/:ruleCategoryIdGet detailed information about a rule category - POSTUpdate rule category details
/rules/categories/:ruleCategoryIdUpdate detailed information about a rule category - DELETEDelete group category
/rules/categories/:ruleCategoryIdDelete a group category. It must have no child groups and no children categories. - GETGet rules tree
/rules/treeGet all available rules and their categories in a tree - GETGet a rule details
/rules/:ruleIdGet the details of a rule - POSTUpdate a rule details
/rules/:ruleIdUpdate the details of a rule - DELETEDelete a rule
/rules/:ruleIdDelete a rule.
Directives
- GETList all directives
/directivesList all directives - PUTCreate a directive
/directivesCreate a new directive from provided parameters. You can specify a source directive to clone it. - GETGet directive details
/directives/:directiveIdGet all information about a given directive - POSTUpdate a directive details
/directives/:directiveIdUpdate directive information - DELETEDelete a directive
/directives/:directiveIdDelete a directive - POSTCheck that update on a directive is valid
/directives/:directiveId/checkCheck that update on a directive is valid
Techniques
- GETList methods
/methodsGet all generic methods metadata - POSTReload methods
/methods/reloadReload methods metadata from file system - GETList all techniques
/techniquesList all technique with their versions - PUTCreate technique
/techniquesCreate a new technique in Rudder from a technique in the technique editor - GETList categories
/techniques/categoriesGet all technique categories - POSTReload techniques
/techniques/reloadReload all techniques metadata from file system - GETList versions
/techniques/versionsList all techniques version - GETTechnique metadata by ID
/techniques/:techniqueIdGet each Technique's versions with their metadata by ID - GETList all directives based on a technique
/techniques/:techniqueId/directivesList all directives based on all version of a technique - GETTechnique metadata by version and ID
/techniques/:techniqueId/:techniqueVersionGet Technique metadata - POSTUpdate technique
/techniques/:techniqueId/:techniqueVersionUpdate technique created with technique editor - DELETEDelete technique
/techniques/:techniqueId/:techniqueVersionDelete a technique from technique editor - GETList all directives based on a version of a technique
/techniques/:techniqueId/:techniqueVersion/directivesList all directives based on a version of a technique - GETTechnique's resources
/techniques/:techniqueId/:techniqueVersion/resourcesGet currently deployed resources of a technique - GETTechnique's revisions
/techniques/:techniqueId/:techniqueVersion/revisionsGet revisions for given technique
Groups
- GETList all groups
/groupsList all groups - PUTCreate a group
/groupsCreate a new group based in provided parameters - PUTCreate a group category
/groups/categoriesCreate a new group category - GETGet group category details
/groups/categories/:groupCategoryIdGet detailed information about a group category - POSTUpdate group category details
/groups/categories/:groupCategoryIdUpdate detailed information about a group category - DELETEDelete group category
/groups/categories/:groupCategoryIdDelete a group category. It must have no child groups and no children categories. - GETGet groups tree
/groups/treeGet all available groups and their categories in a tree - GETGet group details
/groups/:groupIdGet detailed information about a group - POSTUpdate group details
/groups/:groupIdUpdate detailed information about a group - DELETEDelete a group
/groups/:groupIdUpdate detailed information about a group - POSTReload a group
/groups/:groupId/reloadRecompute the content of a group
Nodes
- GETList managed nodes
/nodes?include=minimal&query=&where=&composition=and&select=nodeGet information about the nodes managed by the target server - PUTCreate one or several new nodes
/nodesUse the provided array of node information to create new nodes - POSTTrigger an agent run on all nodes
/nodes/applyPolicyThis API allows to trigger an agent run on all nodes. Response contains a json stating if agent could be started on each node, but not if the run went fine… - GETList pending nodes
/nodes/pending?include=minimal&query=&where=&composition=and&select=nodeGet information about the nodes pending acceptation - POSTUpdate pending Node status
/nodes/pending/:nodeIdAccept or refuse a pending node - GETGet nodes acceptation status
/nodes/status?ids=8403353b-42c4-46f5-a08d-bc77a1a0bad9,rootGet acceptation status (pending, accepted, deleted, unknown) of a list of nodes - GETGet information about a node
/nodes/:nodeId?include=minimalGet details about a given node - POSTUpdate node settings and properties
/nodes/:nodeIdUpdate node settings and properties - DELETEDelete a node
/nodes/:nodeId?mode=moveRemove a node from the Rudder server. It won't be managed anymore. - POSTTrigger an agent run
/nodes/:nodeId/applyPolicyThis API allows to trigger an agent run on the target node. Response is a stream of the actual agent run on the node. - GETGet inherited node properties for a node
/nodes/:nodeId/inheritedPropertiesThis API returns all node properties for a node, including group inherited ones.
Inventories
- GETGet information about inventory processing queue
/inventories/infoProvide information about the current state of the inventory processor - POSTUpload an inventory for processing
/inventories/uploadUpload an inventory to the web application - POSTRestart inventory watcher
/inventories/watcher/restartRestart the inventory watcher if necessary - POSTStart inventory watcher
/inventories/watcher/startStart the inventory watcher if necessary - POSTStop inventory watcher
/inventories/watcher/stopStop the inventory watcher if necessary
Parameters
- GETList all global parameters
/parametersGet the current value of all the global parameters - PUTCreate a new parameter
/parametersCreate a new global parameter - GETGet the value of a parameter
/parameters/:parameterIdGet the current value of a given parameter - POSTUpdate a parameter's value
/parameters/:parameterIdUpdate the properties of a parameter - DELETEDelete a parameter
/parameters/:parameterIdDelete an existing parameter
Archives
- GETGet a ZIP archive of the requested items and their dependencies
/archives/export?rules=a0573b59-e5bd-441b-9031-f307aa21a61e,4cba6eee-3a43-4e17-a608-a4941b6d984f%2B35177d0823791a374de9e16a6ab27e6466fbc8c2&directives=a0573b59-e5bd-441b-9031-f307aa21a61e,4cba6eee-3a43-4e17-a608-a4941b6d984f%2B35177d0823791a374de9e16a6ab27e6466fbc8c2&techniques=userManagement/6.3,fileContent/3.0%2B35177d0823791a374de9e16a6ab27e6466fbc8c2&groups=a0573b59-e5bd-441b-9031-f307aa21a61e,4cba6eee-3a43-4e17-a608-a4941b6d984f%2B35177d0823791a374de9e16a6ab27e6466fbc8c2&include=directives,groupsGet a ZIP archive or rules, directives, techniques and groups with optionally their dependencies - POSTImport a ZIP archive of policies into Rudder
/archives/importImport a ZIP archive of techniques, directives, groups and rules in a saved in a normalized format into Rudder
Settings
- GETList all settings
/settingsGet the current value of all the settings - GETGet allowed networks for a policy server
/settings/allowed_networks/:nodeIdGet the list of allowed networks for a policy server - POSTSet allowed networks for a policy server
/settings/allowed_networks/:nodeIdSet the list of allowed networks for a policy server - POSTModify allowed networks for a policy server
/settings/allowed_networks/:nodeId/diffAdd or delete allowed networks for a policy server - GETGet the value of a setting
/settings/:settingIdGet the current value of a specific setting - POSTSet the value of a setting
/settings/:settingIdSet the current value of a specific setting
System
- GETList archives
/system/archives/:archiveKindList configuration archives - POSTCreate an archive
/system/archives/:archiveKindCreate new archive of the given kind - POSTRestore an archive
/system/archives/:archiveKind/restore/:archiveRestoreKindRestore an archive of the given kind for the given moment - GETGet an archive as a ZIP
/system/archives/:archiveKind/zip/:commitIdGet an archive of the given kind as a zip - GETGet healthcheck
/system/healthcheckRun and get the result of all checks - GETGet server information
/system/infoGet information about the server version - POSTTrigger batch for cleaning unreferenced software
/system/maintenance/purgeSoftwareStart the software cleaning batch asynchronously. - POSTTrigger a new policy generation
/system/regenerate/policiesTrigger a full policy generation - POSTReload both techniques and dynamic groups
/system/reloadReload both techniques and dynamic groups - POSTReload dynamic groups
/system/reload/groupsReload dynamic groups - POSTReload techniques
/system/reload/techniquesReload techniques from local technique library - GETGet server status
/system/statusGet information about current server status - POSTTrigger update of policies
/system/update/policiesUpdate configuration policies if needed
🧩 Change requests
- GETList all change requests
/api/changeRequestsList all change requests - GETGet a change request details
/changeRequests/:changeRequestIdGet a change request details - POSTUpdate a request details
/changeRequests/:changeRequestIdUpdate a change request - DELETEDecline a request details
/changeRequests/:changeRequestIdRefuse a change request - POSTAccept a request details
/changeRequests/:changeRequestId/acceptAccept a change request - GETList user
/usersList all validated and unvalidated users - POSTUpdate validated user list
/validatedUsersAdd and remove user from validated users - DELETERemove an user from validated user list
/validatedUsers/:usernameThe user is again subject to workflow validation
🧩 CVE
- GETGet all CVE details
/cveGet all CVE details - POSTTrigger a CVE check
/cve/checkTrigger a CVE check - GETGet CVE check config
/cve/check/configGet CVE check config - POSTUpdate cve check config
/cve/check/configUpdate cve check config - GETGet last CVE check result
/cve/check/lastGet last CVE check result - POSTGet a list of CVE details
/cve/listGet CVE details, from a list passed as parameter - POSTUpdate CVE database from remote source
/cve/update/Update CVE database from remote source - POSTUpdate CVE database from file system
/cve/update/fsUpdate CVE database from file system
🧩 Data sources
- GETList all data sources
/datasourcesGet the configuration of all present data sources - PUTCreate a data source
/datasourcesCreate a new data source - POSTUpdate properties from data sources
/datasources/reloadUpdate properties from all data source on all nodes. The call is asynchronous. - POSTUpdate properties from data sources
/datasources/reload/:datasourceIdUpdate properties from all data source on all nodes. The call is asynchronous. - GETGet data source configuration
/datasources/:datasourceIdGet the configuration of a data source - POSTUpdate a data source configuration
/datasources/:datasourceIdUpdate the configuration of a data source - DELETEDelete a data source
/datasources/:datasourceIdDelete a data source configuration - POSTUpdate properties for one node from all data sources
/nodes/:nodeId/fetchDataUpdate properties from all data sources on one nodes. The call is asynchronous. - POSTUpdate properties for one node from a data source
/nodes/:nodeId/fetchData/:datasourceIdUpdate properties from a data source on one nodes. The call is asynchronous.
🧩 Scale out Relay
- POSTDemote a relay to simple node
/scaleoutrelay/demote/:nodeIdDemote a relay to a simple node. - POSTPromote a node to relay
/scaleoutrelay/promote/:nodeIdPromote a node to relay
🧩 User Management
- POSTAdd user
/usermanagementAdd a new user - GETList all roles
/usermanagement/rolesGet all available roles and their rights - POSTUpdate user's infos
/usermanagement/update/:usernameRename, change password (pre-hashed or not) and change permission of an user. If a parameter is empty, it will be ignored. - GETList all users
/usermanagement/usersGet the list of all present users and their permissions - GETReload user
/usermanagement/users/reloadReload the users from the file system, in the configuration file - DELETEDelete an user
/usermanagement/:usernameDelete the user and his permissions
🧩 Branding
- GETGet branding configuration
/brandingGet all web interface customization parameters - POSTUpdate web interface customization
/brandingchange color, logo, label etc. - POSTReload branding file
/branding/reloadReload the configuration from file
🧩 Secret Management
- GETList all secrets
/secret/Get the list of all secrets without their value - PUTCreate a secret
/secret/Add a secret - POSTUpdate a secret
/secret/Update a secret and override the value, the name cannot be overridden - GETGet one secret
/secret/:nameGet one secret by his unique name - DELETEDelete a secret
/secret/:nameRemove the secret by his unique name
API details
- Base URL
https://rudder.example.local/rudder/api/latest- Authentication
- An API key in the X-API-Token header
- Operations
- 134 operations on 99 pathsGET 60POST 51DELETE 13PUT 10
- Main resources
- Techniques 15System 13Groups 11Nodes 11Rules 10🧩 Data sources 9🧩 CVE 8🧩 Change requests 8Directives 6Settings 6
- Response formats
application/jsonapplication/octet-streamtext/plain- Description format
- OpenAPI 3.0.3, API version
16 - Links
- Documentation · OpenAPI document · Support
- Listed from
- APIs.guru OpenAPI Directory (CC0-1.0)
Source updated
How to test the Rudder API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Rudder API collection, without the publisher's secrets.
- Add your credentialsThis API uses an API key in the X-API-Token header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “List all endoints” (GET /info), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Rudder API?
Download OpenAPI specification: [openapi.yml](openapi.yml) Introduction Rudder exposes a REST API, enabling the user to interact with Rudder without using the… It is listed under Developer tools and has 134 endpoints.
Who publishes the Rudder API?
It is listed from Rudder's public API description (an OpenAPI document), not published by Rudder on Swastik Codes. Anyone who controls rudder.io can claim the profile by adding a DNS TXT record.
What is the base URL of the Rudder API?
Requests go to https://rudder.example.local/rudder/api/latest. Endpoint paths are added to this base URL.
How do I authenticate with the Rudder API?
With an API key in the X-API-Token header.
How many endpoints does the Rudder API have?
134 operations on 99 paths (60 GET, 51 POST, 13 DELETE, 10 PUT). The largest groups are Techniques, System, Groups, Nodes.
Is forking the Rudder API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.