integrations.sh
← all integrations

Rudder API

OpenAPI apis-guru developer_tools

Download OpenAPI specification: openapi.yml [blocked]

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.
bash
# Version 10curl -X GET -H "X-API-Token: yourToken" https://rudder.example.com/rudder/api/10/rules# Latestcurl -X GET -H "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/rules# Wrong (not an integer) => 404 not foundcurl -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.
bash
# Version 10curl -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 availablecurl -X GET -H "X-API-Token: yourToken" -H "X-API-Version: 3.14" https://rudder.example.com/rudder/api/rules

In 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

VersionRudder versions it appeared inDescription
1Never released (for internal use only)Experimental version
2 to 10 (deprecated)4.3 and beforeThese versions provided the core set of API features for rules, directives, nodes global parameters, change requests and compliance, rudder settings and system API
115.0New system API (replacing old localhost v1 api): status, maintenance operations and server behavior
126.0 and 6.1Node key management
136.2
  • Node status endpoint
  • System health check
  • System maintenance job to purge software [that endpoint was back-ported in 6.1]
147.0
  • Secret management
  • Directive tree
  • Improve techniques management
  • Demote a relay
157.1
  • Package updates in nodes
167.2
  • Create node API included from plugin
  • Configuration archive import/export

Response format

All responses from the API are in the JSON format.

json
{  "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 . 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

FieldTypeDescription
prettifyboolean
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)

FieldTypeDescription
reasonstring
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: ""

changeRequestNamestring
optional		 Set the change request name, is used only if workflows are enabled. The default value depends on the function called

Default value: A default string for each function

changeRequestDescriptionstring
optional		 Set the change request description, is used only if workflows are enabled.

Default value: ""

Passing parameters

Parameters to the API can be sent:

  • As part of the URL for resource identification

  • As data for POST/PUT requests

    • Directly in JSON format

    • As request arguments

As part of the URL for resource identification

Parameters in URLs are used to indicate which resource you want to interact with. The function will not work if this resource is missing.

bash
# Get the Rule of ID "id"curl -H "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/rules/id

CAUTION: To avoid surprising behavior, do not put a '/' at the end of an URL: it would be interpreted as '/[empty string parameter]' and redirected to '/index', likely not what you wanted to do.

Sending data for POST/PUT requests

Directly in JSON format

JSON format is the preferred way to interact with Rudder API for creating or updating resources. You'll also have to set the Content-Type header to application/json (without it the JSON content would be ignored). In a curl POST request, that header can be provided with the -H parameter:

bash
curl -X POST -H "Content-Type: application/json" ...

The supplied file must contain a valid JSON: strings need quotes, booleans and integers don't, etc.

The (human readable) format is:

json
{  "key1": "value1",  "key2": false,  "key3": 42}

Here is an example with inlined data:

bash
# Update the Rule 'id' with a new name, disabled, and setting it one directivecurl -X POST -H "X-API-Token: yourToken" -H  "Content-Type: application/json"https://rudder.example.com/rudder/api/rules/latest/{id}  -d '{ "displayName": "new name", "enabled": false, "directives": "directiveId"}'

You can also pass a supply the JSON in a file:

bash
# Update the Rule 'id' with a new name, disabled, and setting it one directivecurl -X POST -H "X-API-Token: yourToken" -H "Content-Type: application/json" https://rudder.example.com/rudder/api/rules/latest/{id} -d @jsonParam

Note that the general parameters view in the previous chapter cannot be passed in a JSON, and you will need to pass them a URL parameters if you want them to be taken into account (you can't mix JSON and request parameters):

bash
# Update the Rule 'id' with a new name, disabled, and setting it one directive with reason message "Reason used"curl -X POST -H "X-API-Token: yourToken" -H "Content-Type: application/json" "https://rudder.example.com/rudder/api/rules/latest/{id}?reason=Reason used" -d @jsonParam -d "reason=Reason ignored"
Request parameters

In some cases, when you have little, simple data to update, JSON can feel bloated. In such cases, you can use request parameters. You will need to pass one parameter for each data you want to change.

Parameters follow the following schema:

key=value

You can pass parameters by two means:

  • As query parameters: At the end of your url, put a ? then your first parameter and then a & before next parameters. In that case, parameters need to be encoded]
bash
# Update the Rule 'id' with a new name, disabled, and setting it one directivecurl -X POST -H "X-API-Token: yourToken"  https://rudder.example.com/rudder/api/rules/latest/{id}?"displayName=my new name"&"enabled=false"&"directives=aDirectiveId"
  • As request data: You can pass those parameters in the request data, they won't figure in the URL, making it lighter to read, You can pass a file that contains data.
bash
# Update the Rule 'id' with a new name, disabled, and setting it one directive (in file directive-info.json)curl -X POST -H "X-API-Token: yourToken"https://rudder.example.com/rudder/api/rules/latest/{id} -d "displayName=my new name" -d "enabled=false" -d @directive-info.json
Homepage
https://api.apis.guru/v2/specs/rudder.example.local/16.json
Provider
rudder.example.local
OpenAPI version
3.0.3
Spec (JSON)
https://api.apis.guru/v2/specs/rudder.example.local/16/openapi.json
Spec (YAML)
https://api.apis.guru/v2/specs/rudder.example.local/16/openapi.yaml

Tools (136)

Extracted live via the executor SDK.

  • apiInfo.apiGeneralInformations

    List all endpoints and their version

  • apiInfo.apiInformations

    Get the description and the list of supported version for one API endpoint

  • apiInfo.apiSubInformations

    Get all endpoints in the given section with their supported version.

  • archives.export

    Get a ZIP archive or rules, directives, techniques and groups with optionally their dependencies

  • archives.import

    Import a ZIP archive of techniques, directives, groups and rules in a saved in a normalized format into Rudder

  • branding.getBrandingConf

    Get all web interface customization parameters

  • branding.reloadBrandingConf

    Reload the configuration from file

  • branding.updateBRandingConf

    change color, logo, label etc.

  • changeRequests.acceptChangeRequest

    Accept a change request

  • changeRequests.changeRequestDetails

    Get a change request details

  • changeRequests.declineChangeRequest

    Refuse a change request

  • changeRequests.listChangeRequests

    List all change requests

  • changeRequests.listUsers

    List all validated and unvalidated users

  • changeRequests.removeValidatedUser

    The user is again subject to workflow validation

  • changeRequests.saveWorkflowUser

    Add and remove user from validated users

  • changeRequests.updateChangeRequest

    Update a change request

  • compliance.getGlobalCompliance

    Get current global compliance of a Rudder server

  • compliance.getNodeCompliance

    Get current compliance of a node of a Rudder server

  • compliance.getNodesCompliance

    Get current compliance of all the nodes of a Rudder server

  • compliance.getRuleCompliance

    Get current compliance of a rule of a Rudder server

  • compliance.getRulesCompliance

    Get current compliance of all the rules of a Rudder server

  • cve.checkCve

    Trigger a CVE check

  • cve.getAllCve

    Get all CVE details

  • cve.getCveCheckConfiguration

    Get CVE check config

  • cve.getCveList

    Get CVE details, from a list passed as parameter

  • cve.getLastCveCheck

    Get last CVE check result

  • cve.readCvEfromFs

    Update CVE database from file system

  • cve.updateCve

    Update CVE database from remote source

  • cve.updateCveCheckConfiguration

    Update cve check config

  • dataSources.createDataSource

    Create a new data source

  • dataSources.deleteDataSource

    Delete a data source configuration

  • dataSources.getAllDataSources

    Get the configuration of all present data sources

  • dataSources.getDataSource

    Get the configuration of a data source

  • dataSources.reloadAllDatasourcesAllNodes

    Update properties from all data source on all nodes. The call is asynchronous.

  • dataSources.reloadAllDatasourcesOneNode

    Update properties from all data sources on one nodes. The call is asynchronous.

  • dataSources.reloadOneDatasourceAllNodes

    Update properties from all data source on all nodes. The call is asynchronous.

  • dataSources.reloadOneDatasourceOneNode

    Update properties from a data source on one nodes. The call is asynchronous.

  • dataSources.updateDataSource

    Update the configuration of a data source

  • directives.checkDirective

    Check that update on a directive is valid

  • directives.createDirective

    Create a new directive from provided parameters. You can specify a source directive to clone it.

  • directives.deleteDirective

    Delete a directive

  • directives.directiveDetails

    Get all information about a given directive

  • directives.listDirectives

    List all directives

  • directives.updateDirective

    Update directive information

  • groups.createGroup

    Create a new group based in provided parameters

  • groups.createGroupCategory

    Create a new group category

  • groups.deleteGroup

    Update detailed information about a group

  • groups.deleteGroupCategory

    Delete a group category. It must have no child groups and no children categories.

  • groups.getGroupCategoryDetails

    Get detailed information about a group category

  • groups.getGroupTree

    Get all available groups and their categories in a tree

  • groups.groupDetails

    Get detailed information about a group

  • groups.listGroups

    List all groups

  • groups.reloadGroup

    Recompute the content of a group

  • groups.updateGroup

    Update detailed information about a group

  • groups.updateGroupCategory

    Update detailed information about a group category

  • inventories.fileWatcherRestart

    Restart the inventory watcher if necessary

  • inventories.fileWatcherStart

    Start the inventory watcher if necessary

  • inventories.fileWatcherStop

    Stop the inventory watcher if necessary

  • inventories.queueInformation

    Provide information about the current state of the inventory processor

  • inventories.uploadInventory

    Upload an inventory to the web application

  • nodes.applyNode

    This API allows to trigger an agent run on the target node. Response is a stream of the actual agent run on the node.

  • nodes.applyPolicyAllNodes

    This 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 and do not display any output from it. You can see the result of the run in Rudder web interface or in the each agent logs.

  • nodes.changePendingNodeStatus

    Accept or refuse a pending node

  • nodes.createNodes

    Use the provided array of node information to create new nodes

  • nodes.deleteNode

    Remove a node from the Rudder server. It won't be managed anymore.

  • nodes.getNodesStatus

    Get acceptation status (pending, accepted, deleted, unknown) of a list of nodes

  • nodes.listAcceptedNodes

    Get information about the nodes managed by the target server

  • nodes.listPendingNodes

    Get information about the nodes pending acceptation

  • nodes.nodeDetails

    Get details about a given node

  • nodes.nodeInheritedProperties

    This API returns all node properties for a node, including group inherited ones.

  • nodes.updateNode

    Update node settings and properties

  • parameters.createParameter

    Create a new global parameter

  • parameters.deleteParameter

    Delete an existing parameter

  • parameters.listParameters

    Get the current value of all the global parameters

  • parameters.parameterDetails

    Get the current value of a given parameter

  • parameters.updateParameter

    Update the properties of a parameter

  • rules.createRule

    Create a new rule. You can specify a source rule to clone it.

  • rules.createRuleCategory

    Create a new rule category

  • rules.deleteRule

    Delete a rule.

  • rules.deleteRuleCategory

    Delete a group category. It must have no child groups and no children categories.

  • rules.getRuleCategoryDetails

    Get detailed information about a rule category

  • rules.getRuleTree

    Get all available rules and their categories in a tree

  • rules.listRules

    List all rules

  • rules.ruleDetails

    Get the details of a rule

  • rules.updateRule

    Update the details of a rule

  • rules.updateRuleCategory

    Update detailed information about a rule category

  • scaleOutRelay.demoteToNode

    Demote a relay to a simple node.

  • scaleOutRelay.promoteToRelay

    Promote a node to relay

  • secretManagement.addSecret

    Add a secret

  • secretManagement.deleteSecret

    Remove the secret by his unique name

  • secretManagement.getAllSecrets

    Get the list of all secrets without their value

  • secretManagement.getSecret

    Get one secret by his unique name

  • secretManagement.updateSecret

    Update a secret and override the value, the name cannot be overridden

  • settings.getAllowedNetworks

    Get the list of allowed networks for a policy server

  • settings.getAllSettings

    Get the current value of all the settings

  • settings.getSetting

    Get the current value of a specific setting

  • settings.modifyAllowedNetworks

    Add or delete allowed networks for a policy server

  • settings.modifySetting

    Set the current value of a specific setting

  • settings.setAllowedNetworks

    Set the list of allowed networks for a policy server

  • status.none

    An 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 versioned, so the path is just /api/status;
    • it returns a plain text message.
  • system.createArchive

    Create new archive of the given kind

  • system.getHealthcheckResult

    Run and get the result of all checks

  • system.getStatus

    Get information about current server status

  • system.getSystemInfo

    Get information about the server version

  • system.getZipArchive

    Get an archive of the given kind as a zip

  • system.listArchives

    List configuration archives

  • system.purgeSoftware

    Start the software cleaning batch asynchronously.

  • system.regeneratePolicies

    Trigger a full policy generation

  • system.reloadAll

    Reload both techniques and dynamic groups

  • system.reloadGroups

    Reload dynamic groups

  • system.reloadTechniques

    Reload techniques from local technique library

  • system.restoreArchive

    Restore an archive of the given kind for the given moment

  • system.updatePolicies

    Update configuration policies if needed

  • techniques.createTechnique

    Create a new technique in Rudder from a technique in the technique editor

  • techniques.deleteTechnique

    Delete a technique from technique editor

  • techniques.getTechniqueAllVersion

    Get each Technique's versions with their metadata by ID

  • techniques.getTechniqueAllVersionId

    Get Technique metadata

  • techniques.getTechniquesResources

    Get currently deployed resources of a technique

  • techniques.listTechniques

    List all technique with their versions

  • techniques.listTechniquesDirectives

    List all directives based on all version of a technique

  • techniques.listTechniquesVersions

    List all techniques version

  • techniques.listTechniqueVersionDirectives

    List all directives based on a version of a technique

  • techniques.methods

    Get all generic methods metadata

  • techniques.postReload

    Reload all techniques metadata from file system

  • techniques.reloadMethods

    Reload methods metadata from file system

  • techniques.techniqueCategories

    Get all technique categories

  • techniques.techniqueRevisions

    Get revisions for given technique

  • techniques.updateTechnique

    Update technique created with technique editor

  • userManagement.addUser

    Add a new user

  • userManagement.deleteUser

    Delete the user and his permissions

  • userManagement.getRole

    Get all available roles and their rights

  • userManagement.getUserInfo

    Get the list of all present users and their permissions

  • userManagement.reloadUserConf

    Reload the users from the file system, in the configuration file

  • userManagement.updateUser

    Rename, change password (pre-hashed or not) and change permission of an user. If a parameter is empty, it will be ignored.

  • openapi.previewSpec

    Preview an OpenAPI document before adding it as a source

  • openapi.addSource

    Add an OpenAPI source and register its operations as tools