Rudder API (13)

Rudder developers: dev@rudder.io URL: https://www.rudder.io License: CC-BY-SA 2.0

Download OpenAPI specification: 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/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

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]

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 function called

Default value: A default string for each function

changeRequestDescription string
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.

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

CAUTION: To avoid suprising 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:

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:

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

Here is an example with inlined data:

# Update the Rule 'id' with a new name, disabled, and setting it one directive
curl -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:

# Update the Rule 'id' with a new name, disabled, and setting it one directive
curl -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):

# 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:

# Update the Rule 'id' with a new name, disabled, and setting it one directive
curl -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.
# 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

Authentication

API-Tokens

Authenticating against the API is mandatory for every request, as sensitive information like inventories or configuration rules may get exposed. It is done using a dedicated API Account, than can be created in the web interface on the 'API Accounts' page located inside the Administration part.

API Tokens settings

API Accounts are not linked to standard user accounts, and currently give full administrative privileges: they must be secured adequately. Once you have created an API account, you get a token that will be needed to authenticate every request. This token is the API equivalent of a password, and must be secured just like a password would be.

On any call to the API, you will need to add a X-API-Token header to your request to authenticate:

curl --request GET --header "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/rules

If you perform any action (creation, update, deletion) using the API, the event log generated will record the API account as the user.

Security Scheme Type API Key
Header parameter name: X-API-Token

API Info

Information about API endpoints and versions

List all endoints

List all endpoints and their version

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "apiGeneralInformations"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/info

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "apiGeneralInformations",
  • "data": {
    }
}

Get information about one API endpoint

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

Authorizations:
path Parameters
endpointName
required
string
Example: listAcceptedNodes

Name of the endpoint for which one wants information

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "apiInformations"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/info/details/listAcceptedNodes

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "apiInformations",
  • "data": {
    }
}

Get information on endpoint in a section

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

Authorizations:
path Parameters
sectionId
required
string
Example: nodes

Id of the API section

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "apiSubInformations"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/info/nodes

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "apiSubInformations",
  • "data": {
    }
}

Compliance

Access compliance data

Global compliance

Get current global compliance of a Rudder server

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "getGlobalCompliance"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/compliance?prettify=true'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getGlobalCompliance",
  • "data": {
    }
}

Compliance details for all nodes

Get current compliance of all the nodes of a Rudder server

Authorizations:
query Parameters
level
integer
Default: 10
Example: level=4

Number of depth level of compliance objects to display (1:rules, 2:directives, 3:components, 4:nodes, 5:values, 6:reports)

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "getNodesCompliance"

The id of the action

required
object

Request samples

# To get the compliance information of a specific node
curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/compliance/nodes?level=2'

# To get the list of nodes which have a compliance <100 for a given directive (c5881268-5612-48f2-8ef4-0ab8387fccd6) 
curl -k -H "X-API-Token: yourToken" -X GET "https://rudder.example.com/rudder/api/latest/compliance/nodes?level=3" \
| jq '[.data.nodes[] 
  | {
      "nodeid":.id, 
      "dirs": [.rules[].directives[]] 
        | map(select(.id == "c5881268-5612-48f2-8ef4-0ab8387fccd6" and .compliance < 100)) 
    }
  ] 
| map(select(.dirs | length != 0)) 
| [.[] |
    {"nodeid":.nodeid, "comp":.dirs[0].complianceDetails}
  ]'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getNodesCompliance",
  • "data": {
    }
}

Compliance details by node

Get current compliance of a node of a Rudder server

Authorizations:
path Parameters
nodeId
required
string <uuid (or "root")>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Id of the target node

query Parameters
level
integer
Default: 10
Example: level=4

Number of depth level of compliance objects to display (1:rules, 2:directives, 3:components, 4:nodes, 5:values, 6:reports)

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "getNodeCompliance"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/compliance/nodes/root?level=1'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getNodeCompliance",
  • "data": {
    }
}

Compliance details for all rules

Get current compliance of all the rules of a Rudder server

Authorizations:
query Parameters
level
integer
Default: 10
Example: level=4

Number of depth level of compliance objects to display (1:rules, 2:directives, 3:components, 4:nodes, 5:values, 6:reports)

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "getRulesCompliance"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/compliance/rules?level=2'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getRulesCompliance",
  • "data": {
    }
}

Compliance details by rule

Get current compliance of a rule of a Rudder server

Authorizations:
path Parameters
ruleId
required
string <uuid>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Id of the target rule

query Parameters
level
integer
Default: 10
Example: level=4

Number of depth level of compliance objects to display (1:rules, 2:directives, 3:components, 4:nodes, 5:values, 6:reports)

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "getRuleCompliance"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/compliance/rules?level=2'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getRuleCompliance",
  • "data": {
    }
}

Rules

Rules management

List all rules

List all rules

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "listRules"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/rules'

# To get information about the target (included/excluded) groups of the rules
curl -H "X-API-Token: yourToken" -X GET 'https://rudder.example.com/rudder/api/latest/rules' | jq '.data.rules[] | {"d": .displayName, "id":.id, "inc": .targets[].include?.or, "exc":.targets[].exclude?.or}'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "listRules",
  • "data": {
    }
}

Create a rule

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

Authorizations:
Request Body schema: application/json
source
string <uuid>

The id of the rule the clone will be based onto. If this parameter if provided, the new rule will be a clone of this source. Other value will override values from the source.

id
string <uuid>

Rule id

displayName
string

Rule name

shortDescription
string

One line rule description

longDescription
string

Rule documentation

category
string <uuid>

The parent category id. If provided, the new rule will be in this parent category

directives
Array of strings

Directives linked to the rule

Array of objects (rule-targets) [ items ]

Node and special groups targeted by that rule

enabled
boolean

Is the rule enabled

system
boolean

If true it is an internal Rudder rule

Array of objects[ items ]

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "createRule"

The id of the action

required
object

Request samples

Content type
application/json
{
  • "source": "b9f6d98a-28bc-4d80-90f7-d2f14269e215",
  • "id": "0c1713ae-cb9d-4f7b-abda-ca38c5d643ea",
  • "displayName": "Security policy",
  • "shortDescription": "Baseline applying CIS guidelines",
  • "longDescription": "This rules should be applied to all Linux nodes required basic hardening",
  • "category": "38e0c6ea-917f-47b8-82e0-e6a1d3dd62ca",
  • "directives": [
    ],
  • "targets": [
    ],
  • "enabled": true,
  • "system": false,
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "createRule",
  • "data": {
    }
}

Create a rule category

Create a new rule category

Authorizations:
Request Body schema: application/json
parent
required
string <uuid>

The parent category of the rules

id
string <uuid>
Default: "{autogenerated}"

Rule category id, only provide it when needed.

name
required
string

Name of the rule category

description
string

Rules category description

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "CreateRuleCategory"

The id of the action

required
object

Request samples

Content type
application/json
{
  • "parent": "b9f6d98a-28bc-4d80-90f7-d2f14269e215",
  • "id": "32d013f7-b6d8-46c8-99d3-016307fa66c0",
  • "name": "Security policies",
  • "description": "Baseline applying CIS guidelines"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "CreateRuleCategory",
  • "data": {
    }
}

Get rule category details

Get detailed information about a rule category

Authorizations:
path Parameters
ruleCategoryId
required
string <uuid>
Example: e0a311fa-f7b2-4f9e-89a9-db517b9c6b90

Rule category id

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "GetRuleCategoryDetails"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/rules/categories/4306143d-eabf-4478-b7b1-1616f4aa02b5?prettify=true'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "GetRuleCategoryDetails",
  • "data": {
    }
}

Delete group category

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

Authorizations:
path Parameters
ruleCategoryId
required
string <uuid>
Example: e0a311fa-f7b2-4f9e-89a9-db517b9c6b90

Rule category id

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "DeleteRuleCategory"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request DELETE 'https://rudder.example.com/rudder/api/latest/rules/categories/4306143d-eabf-4478-b7b1-1616f4aa02b5?prettify=true'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "DeleteRuleCategory",
  • "data": {
    }
}

Update rule category details

Update detailed information about a rule category

Authorizations:
path Parameters
ruleCategoryId
required
string <uuid>
Example: e0a311fa-f7b2-4f9e-89a9-db517b9c6b90

Rule category id

Request Body schema: application/json
parent
required
string <uuid>

The parent category of the rules

name
required
string

Name of the rule category

description
string

Rules category description

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "UpdateRuleCategory"

The id of the action

required
object

Request samples

Content type
application/json
{
  • "parent": "b9f6d98a-28bc-4d80-90f7-d2f14269e215",
  • "name": "Security policies",
  • "description": "Baseline applying CIS guidelines"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "UpdateRuleCategory",
  • "data": {
    }
}

Get rules tree

Get all available rules and their categories in a tree

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "GetRuleTree"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/rules/tree?prettify=true'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "GetRuleTree",
  • "data": {
    }
}

Get a rule details

Get the details of a rule

Authorizations:
path Parameters
ruleId
required
string <uuid>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Id of the target rule

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "ruleDetails"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/rules/06ba8940-ed6c-4102-ba46-93d640a64c36'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "ruleDetails",
  • "data": {
    }
}

Update a rule details

Update the details of a rule

Authorizations:
path Parameters
ruleId
required
string <uuid>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Id of the target rule

Request Body schema: application/json
id
string <uuid>

Rule id

displayName
string

Rule name

shortDescription
string

One line rule description

longDescription
string

Rule documentation

category
string <uuid>

The parent category id.

directives
Array of strings

Directives linked to the rule

Array of objects (rule-targets) [ items ]

Node and special groups targeted by that rule

enabled
boolean

Is the rule enabled

system
boolean

If true it is an internal Rudder rule

Array of objects[ items ]

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "updateRule"

The id of the action

required
object

Request samples

Content type
application/json
{
  • "id": "0c1713ae-cb9d-4f7b-abda-ca38c5d643ea",
  • "displayName": "Security policy",
  • "shortDescription": "Baseline applying CIS guidelines",
  • "longDescription": "This rules should be applied to all Linux nodes required basic hardening",
  • "category": "38e0c6ea-917f-47b8-82e0-e6a1d3dd62ca",
  • "directives": [
    ],
  • "targets": [
    ],
  • "enabled": true,
  • "system": false,
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "updateRule",
  • "data": {
    }
}

Delete a rule

Delete a rule.

Authorizations:
path Parameters
ruleId
required
string <uuid>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Id of the target rule

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "deleteRule"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request DELETE 'https://rudder.example.com/rudder/api/latest/rules/176ad06b-ed02-4da3-8053-16225d217741'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "deleteRule",
  • "data": {
    }
}

Directives

Directives management

List all directives

List all directives

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "listDirectives"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/directives

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "listDirectives",
  • "data": {
    }
}

Create a directive

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

Authorizations:
Request Body schema: application/json
source
string <uuid>

The id of the directive the clone will be based onto. If this parameter if provided, the new directive will be a clone of this source. Other value will override values from the source.

id
string <uuid>

Directive id

displayName
string

Human readable name of the directive

shortDescription
string

One line directive description

longDescription
string <markdown>

Description of the technique (rendered as markdown)

techniqueName
string

Directive id

techniqueVersion
string

Directive id

priority
integer [ 0 .. 10 ]

Directive priority. 0 has highest priority.

enabled
boolean

Is the directive enabled

system
boolean

If true it is an internal Rudder directive

Array of objects[ items ]
parameters
object

Directive parameters (depends on the source technique)

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "createDirective"

The id of the action

required
object

Request samples

Content type
application/json
{
  • "source": "b9f6d98a-28bc-4d80-90f7-d2f14269e215",
  • "id": "91252ea2-feb2-412d-8599-c6945fee02c4",
  • "displayName": "91252ea2-feb2-412d-8599-c6945fee02c4",
  • "shortDescription": "91252ea2-feb2-412d-8599-c6945fee02c4",
  • "longDescription": "# Documentation\n* [Ticket link](https://tickets.example.com/issues/3456)",
  • "techniqueName": "userManagement",
  • "techniqueVersion": "8.0",
  • "priority": 5,
  • "enabled": true,
  • "system": false,
  • "tags": [
    ],
  • "parameters": {
    }
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "createDirective",
  • "data": {
    }
}

Get directive details

Get all information about a given directive

Authorizations:
path Parameters
directiveId
required
string <uuid>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Id of the directive

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "directiveDetails"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/directives/17dadf50-6056-4c8b-a935-6b97d14b89a7

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "directiveDetails",
  • "data": {
    }
}

Delete a directive

Delete a directive

Authorizations:
path Parameters
directiveId
required
string <uuid>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Id of the directive

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "deleteDirective"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request DELETE https://rudder.example.com/rudder/api/latest/directives/17dadf50-6056-4c8b-a935-6b97d14b89a7

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "deleteDirective",
  • "data": {
    }
}

Update a directive details

Update directive information

Authorizations:
path Parameters
directiveId
required
string <uuid>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Id of the directive

Request Body schema: application/json
id
string <uuid>

Directive id

displayName
string

Human readable name of the directive

shortDescription
string

One line directive description

longDescription
string <markdown>

Description of the technique (rendered as markdown)

techniqueName
string

Directive id

techniqueVersion
string

Directive id

priority
integer [ 0 .. 10 ]

Directive priority. 0 has highest priority.

enabled
boolean

Is the directive enabled

system
boolean

If true it is an internal Rudder directive

policyMode
string
Enum: "enforce" "audit"

Policy mode of the directive

Array of objects[ items ]
parameters
object

Directive parameters (depends on the source technique)

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "updateDirective"

The id of the action

required
object

Request samples

Content type
application/json
{
  • "id": "91252ea2-feb2-412d-8599-c6945fee02c4",
  • "displayName": "91252ea2-feb2-412d-8599-c6945fee02c4",
  • "shortDescription": "91252ea2-feb2-412d-8599-c6945fee02c4",
  • "longDescription": "# Documentation\n* [Ticket link](https://tickets.example.com/issues/3456)",
  • "techniqueName": "userManagement",
  • "techniqueVersion": "8.0",
  • "priority": 5,
  • "enabled": true,
  • "system": false,
  • "policyMode": "audit",
  • "tags": [
    ],
  • "parameters": {
    }
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "updateDirective",
  • "data": {
    }
}

Check that update on a directive is valid

Check that update on a directive is valid

Authorizations:
path Parameters
directiveId
required
string <uuid>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Id of the directive

Request Body schema: application/json
id
string <uuid>

Directive id

displayName
string

Human readable name of the directive

shortDescription
string

One line directive description

longDescription
string <markdown>

Description of the technique (rendered as markdown)

techniqueName
string

Directive id

techniqueVersion
string

Directive id

priority
integer [ 0 .. 10 ]

Directive priority. 0 has highest priority.

enabled
boolean

Is the directive enabled

system
boolean

If true it is an internal Rudder directive

policyMode
string
Enum: "enforce" "audit"

Policy mode of the directive

Array of objects[ items ]
parameters
object

Directive parameters (depends on the source technique)

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "checkDirective"

The id of the action

required
object

Request samples

Content type
application/json
{
  • "id": "91252ea2-feb2-412d-8599-c6945fee02c4",
  • "displayName": "91252ea2-feb2-412d-8599-c6945fee02c4",
  • "shortDescription": "91252ea2-feb2-412d-8599-c6945fee02c4",
  • "longDescription": "# Documentation\n* [Ticket link](https://tickets.example.com/issues/3456)",
  • "techniqueName": "userManagement",
  • "techniqueVersion": "8.0",
  • "priority": 5,
  • "enabled": true,
  • "system": false,
  • "policyMode": "audit",
  • "tags": [
    ],
  • "parameters": {
    }
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "checkDirective",
  • "data": {
    }
}

Techniques

Techniques management

List all techniques

List all technique with their versions

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "listTechniques"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/techniques

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "listTechniques",
  • "data": {
    }
}

List all directives based on a technique

List all directives based on all version of a technique

Authorizations:
path Parameters
techniqueName
required
string
Example: userManagement

Technique name

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "listTechniquesDirectives"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/techniques/checkGenericFileContent/directives

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "listTechniquesDirectives",
  • "data": {
    }
}

List all directives based on a version of a technique

List all directives based on a version of a technique

Authorizations:
path Parameters
techniqueName
required
string
Example: userManagement

Technique name

techniqueVersion
required
string
Example: 6.0

Technique version

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "listTechniqueDirectives"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/techniques/checkGenericFileContent/6.0/directives

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "listTechniqueDirectives",
  • "data": {
    }
}

Groups

Groups management

List all groups

List all groups

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "listGroups"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/groups

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "listGroups",
  • "data": {
    }
}

Create a group

Create a new group based in provided parameters

Authorizations:
Request Body schema: application/json
source
string <uuid>

The id of the group the clone will be based onto. If this parameter if provided, the new group will be a clone of this source. Other value will override values from the source.

category
required
string <uuid>

Id of the new group's category

id
string <uuid>
Default: "{autogenerated}"

Group id, only provide it when needed.

displayName
required
string

Name of the group

description
string

Group description

object

The criteria defining the group. If not provided, the group will be empty.

dynamic
boolean
Default: true

Should the group be dynamically refreshed (if not, it is a static group)

enabled
boolean
Default: true

Enable or disable the group

Array of objects[ items ]

Group properties

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "createGroup"

The id of the action

required
object

Request samples

Content type
application/json
{
  • "source": "b9f6d98a-28bc-4d80-90f7-d2f14269e215",
  • "category": "e17ecf6a-a9f2-44de-a97c-116d24d30ff4",
  • "id": "32d013f7-b6d8-46c8-99d3-016307fa66c0",
  • "displayName": "Ubuntu 18.04 nodes",
  • "description": "Documentation for the group",
  • "query": {
    },
  • "dynamic": true,
  • "enabled": true,
  • "properties": [
    ]
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "createGroup",
  • "data": {
    }
}

Create a group category

Create a new group category

Authorizations:
Request Body schema: application/json
parent
required
string <uuid>

The parent category of the groups

id
string <uuid>
Default: "{autogenerated}"

Group category id, only provide it when needed.

name
required
string

Name of the group category

description
string

Group category description

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "CreateGroupCategory"

The id of the action

required
object

Request samples

Content type
application/json
{
  • "parent": "b9f6d98a-28bc-4d80-90f7-d2f14269e215",
  • "id": "32d013f7-b6d8-46c8-99d3-016307fa66c0",
  • "name": "Hardware groups",
  • "description": "Nodes by hardware provider"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "CreateGroupCategory",
  • "data": {
    }
}

Get group category details

Get detailed information about a group category

Authorizations:
path Parameters
groupCategoryId
required
string <uuid>
Example: e0a311fa-f7b2-4f9e-89a9-db517b9c6b90

Group category id

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "GetGroupCategoryDetails"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/groups/categories/4306143d-eabf-4478-b7b1-1616f4aa02b5'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "GetGroupCategoryDetails",
  • "data": {
    }
}

Delete group category

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

Authorizations:
path Parameters
groupCategoryId
required
string <uuid>
Example: e0a311fa-f7b2-4f9e-89a9-db517b9c6b90

Group category id

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "DeleteGroupCategory"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request DELETE 'https://rudder.example.com/rudder/api/latest/groups/categories/4306143d-eabf-4478-b7b1-1616f4aa02b5'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "DeleteGroupCategory",
  • "data": {
    }
}

Update group category details

Update detailed information about a group category

Authorizations:
path Parameters
groupCategoryId
required
string <uuid>
Example: e0a311fa-f7b2-4f9e-89a9-db517b9c6b90

Group category id

Request Body schema: application/json
parent
required
string <uuid>

The parent category of the groups

name
required
string

Name of the group category

description
string

Group category description

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "UpdateGroupCategory"

The id of the action

required
object

Request samples

Content type
application/json
{
  • "parent": "b9f6d98a-28bc-4d80-90f7-d2f14269e215",
  • "name": "Hardware groups",
  • "description": "Nodes by hardware provider"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "UpdateGroupCategory",
  • "data": {
    }
}

Get groups tree

Get all available groups and their categories in a tree

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "GetGroupTree"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/groups/tree

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "GetGroupTree",
  • "data": {
    }
}

Get group details

Get detailed information about a group

Authorizations:
path Parameters
groupId
required
string <uuid>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Id of the group

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "groupDetails"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/groups/17dadf50-6056-4c8b-a935-6b97d14b89a7'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "groupDetails",
  • "data": {
    }
}

Update group details

Update detailed information about a group

Authorizations:
path Parameters
groupId
required
string <uuid>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Id of the group

Request Body schema: application/json
category
string <uuid>

Id of the new group's category

displayName
string

Name of the group

description
string

Group description

object

The criteria defining the group. If not provided, the group will be empty.

dynamic
boolean
Default: true

Should the group be dynamically refreshed (if not, it is a static group)

enabled
boolean
Default: true

Enable or disable the group

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "updateGroup"

The id of the action

required
object

Request samples

Content type
application/json
{
  • "category": "e17ecf6a-a9f2-44de-a97c-116d24d30ff4",
  • "displayName": "Ubuntu 18.04 nodes",
  • "description": "Documentation for the group",
  • "query": {
    },
  • "dynamic": true,
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "updateGroup",
  • "data": {
    }
}

Delete a group

Update detailed information about a group

Authorizations:
path Parameters
groupId
required
string <uuid>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Id of the group

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "deleteGroup"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request DELETE 'https://rudder.example.com/rudder/api/latest/groups/17dadf50-6056-4c8b-a935-6b97d14b89a7'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "deleteGroup",
  • "data": {
    }
}

Reload a group

Recompute the content of a group

Authorizations:
path Parameters
groupId
required
string <uuid>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Id of the group

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "reloadGroup"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/groups/17dadf50-6056-4c8b-a935-6b97d14b89a7/reload'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "reloadGroup",
  • "data": {
    }
}

Nodes

Nodes management

List managed nodes

Get information about the nodes managed by the target server

Authorizations:
query Parameters
include
string <comma-separated list>
Default: "default"
Example: include=minimal

Level of information to include from the node inventory. Some base levels are defined (minimal, default, full). You can add fields you want to a base level by adding them to the list, possible values are keys from json answer. If you don't provide a base level, they will be added to default level, so if you only want os details, use minimal,os as the value for this parameter.

  • minimal includes: id, hostname and status
  • default includes minimal plus architectureDescription, description, ipAddresses, lastRunDate, lastInventoryDate, machine, os, managementTechnology, policyServerId, properties (be careful! Only node own properties, if you also need inherited properties, look at the dedicated /nodes/{id}/inheritedProperties endpoint), policyMode , ram and timezone
  • full includes: default plus accounts, bios, controllers, environmentVariables, fileSystems, managementTechnologyDetails, memories, networkInterfaces, ports, processes, processors, slots, software, sound, storage, videos and virtualMachines
object

The criterion you want to find for your nodes. Replaces the where, composition and select parameters in a single parameter.

Array of objects[ items ]

The criterion you want to find for your nodes

composition
string
Default: "and"
Enum: "and" "or"
Example: composition=and

Boolean operator to use between each where criteria.

select
string
Default: "node"

What kind of data we want to include. Here we can get policy servers/relay by setting nodeAndPolicyServer. Only used if where is defined.

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "listAcceptedNodes"

The id of the action

required
object

Information about the nodes

Request samples

# To get the Linux nodes with a hostname starting with "node1"
curl -g --header "X-API-Token: yourToken" 'https://rudder.example.com/rudder/api/latest/nodes?where=[{"objectType":"node","attribute":"OS","comparator":"eq","value":"Linux"},{"objectType":"node","attribute":"nodeHostname","comparator":"regex","value":"node1.*"}]&composition=And'

# To get the list of nodes with their agent version
curl -k -H "X-API-Token: yourToken" -X GET "https://rudder.example.com/rudder/api/latest/nodes?include=minimal,managementTechnology" | jq '.data.nodes[] | {"id": .id, "version": .managementTechnology[].version}'

# To get information about the eth0 interface of a specific node
curl -k -H "X-API-Token: yourToken" -H "Content-Type: application/json" -X GET 'https://rudder.example.com/rudder/api/latest/nodes/8b168194-c0b4-41ab-b2b5-9571a8906d59?include=networkInterfaces' | jq '.data.nodes[].networkInterfaces[] | select(.name == "eth0")'
# It gives:
#
#{
# "name": "eth0",
# "type": "ethernet",
# "status": "Up",
# "macAddress": "52:54:00:49:45:ac",
# "ipAddresses": [
#   "fe80:0:0:0:5054:ff:fe49:45ac",
#   "192.168.110.21"
# ]
#}

# To get information about the nodes running a JVM process
#
# This gets information about nodes with processes matching the quesry, and then extract the flat list of matching processes
curl -g -s -H "X-API-Token: yourToken" 'https://rudder.example.com/rudder/api/latest/nodes?include=minimal,processes&where=[{"objectType":"process","attribute":"commandName","comparator":"regex","value":".*(java|jre|jdk).*"}]' | jq -r '.data.nodes[] | [ { hostname } + .processes[] ][] | select( .name | test(".*(java|jdk|jre).*")) | [.hostname, .user, .name] | @tsv' | cut -c -120
# It gives:
#
# node1.example.com	jenkins	java -jar remoting.jar -workDir /home/jenkins -jar-cache /home/jenkins/rem
# node2.example.com	tomcat8	/usr/lib/jvm/java-11-openjdk-amd64//bin/java -Djava.util.logging.config.fi

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "listAcceptedNodes",
  • "data": {
    }
}

Trigger an agent run on all nodes

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.

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "applyPolicyAllNodes"

The id of the action

required
Array of objects[ items ]

Request samples

curl --header "X-API-Token: yourToken" --request POST --header "Content-Type: application/json" https://rudder.example.com/rudder/api/latest/nodes/applyPolicy

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "applyPolicyAllNodes",
  • "data": [
    ]
}

List pending nodes

Get information about the nodes pending acceptation

Authorizations:
query Parameters
include
string <comma-separated list>
Default: "default"
Example: include=minimal

Level of information to include from the node inventory. Some base levels are defined (minimal, default, full). You can add fields you want to a base level by adding them to the list, possible values are keys from json answer. If you don't provide a base level, they will be added to default level, so if you only want os details, use minimal,os as the value for this parameter.

  • minimal includes: id, hostname and status
  • default includes minimal plus architectureDescription, description, ipAddresses, lastRunDate, lastInventoryDate, machine, os, managementTechnology, policyServerId, properties (be careful! Only node own properties, if you also need inherited properties, look at the dedicated /nodes/{id}/inheritedProperties endpoint), policyMode , ram and timezone
  • full includes: default plus accounts, bios, controllers, environmentVariables, fileSystems, managementTechnologyDetails, memories, networkInterfaces, ports, processes, processors, slots, software, sound, storage, videos and virtualMachines
object

The criterion you want to find for your nodes. Replaces the where, composition and select parameters in a single parameter.

Array of objects[ items ]

The criterion you want to find for your nodes

composition
string
Default: "and"
Enum: "and" "or"
Example: composition=and

Boolean operator to use between each where criteria.

select
string
Default: "node"

What kind of data we want to include. Here we can get policy servers/relay by setting nodeAndPolicyServer. Only used if where is defined.

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "listPendingNodes"

The id of the action

required
object

Information about the nodes

Request samples

# To get the list of pending nodes
curl --header "X-API-Token: yourToken" 'https://rudder.example.com/rudder/api/latest/nodes/pending'

# To get the pending Linux nodes with a hostname starting with "node1"
curl --header "X-API-Token: yourToken" 'https://rudder.example.com/rudder/api/latest/nodes/pending?where=\[\{"objectType":"node","attribute":"OS","comparator":"eq","value":"Linux"\},\{"objectType":"node","attribute":"nodeHostname","comparator":"regex","value":"node1.*"\}\]'

# To get the list of pending nodes with their agent version
curl -k -H "X-API-Token: yourToken" -X GET "https://rudder.example.com/rudder/api/latest/nodes/pending?include=minimal,managementTechnology" | jq '.data.nodes[] | {"id": .id, "version": .managementTechnology[].version}'



Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "listPendingNodes",
  • "data": {
    }
}

Update pending Node status

Accept or refuse a pending node

Authorizations:
path Parameters
nodeId
required
string <uuid (or "root")>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Id of the target node

Request Body schema: application/json
status
string
Enum: "accepted" "refused"

New status of the pending node

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "changePendingNodeStatus"

The id of the action

required
object

Information about the node

Request samples

Content type
application/json
{
  • "status": "accepted"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "changePendingNodeStatus",
  • "data": {
    }
}

Get nodes acceptation status

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

Authorizations:
query Parameters
ids
required
string <comma-separated list>
Default: "default"
Example: ids=8403353b-42c4-46f5-a08d-bc77a1a0bad9,root

Comma separated list of node Ids

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "getNodesStatus"

The id of the action

required
object

List of nodeId and associated status

Request samples

curl --header "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/nodes/status?ids=17dadf50-6056-4c8b-a935-6b97d14b89a7,b9a71482-5030-4699-984d-b03d28bbbf36

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getNodesStatus",
  • "data": {
    }
}

Get information about a node

Get details about a given node

Authorizations:
path Parameters
nodeId
required
string <uuid (or "root")>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Id of the target node

query Parameters
include
string <comma-separated list>
Default: "default"
Example: include=minimal

Level of information to include from the node inventory. Some base levels are defined (minimal, default, full). You can add fields you want to a base level by adding them to the list, possible values are keys from json answer. If you don't provide a base level, they will be added to default level, so if you only want os details, use minimal,os as the value for this parameter.

  • minimal includes: id, hostname and status
  • default includes minimal plus architectureDescription, description, ipAddresses, lastRunDate, lastInventoryDate, machine, os, managementTechnology, policyServerId, properties (be careful! Only node own properties, if you also need inherited properties, look at the dedicated /nodes/{id}/inheritedProperties endpoint), policyMode , ram and timezone
  • full includes: default plus accounts, bios, controllers, environmentVariables, fileSystems, managementTechnologyDetails, memories, networkInterfaces, ports, processes, processors, slots, software, sound, storage, videos and virtualMachines

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "nodeDetails"

The id of the action

required
object

Information about the node

Request samples

curl --header "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/nodes/17dadf50-6056-4c8b-a935-6b97d14b89a7\?include=full

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "nodeDetails",
  • "data": {
    }
}

Update node settings and properties

Update node settings and properties

Authorizations:
path Parameters
nodeId
required
string <uuid (or "root")>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Id of the target node

Request Body schema: application/json
Array of objects[ items ]
policyMode
string
Enum: "audit" "enforce" "default"

In which mode the node will apply its configuration policy. Use default to use the global mode.

state
string
Enum: "enabled" "ignored" "empty-policies" "initializing" "preparing-eol"

The node life cycle state. See dedicated doc for more information.

object (agent-key)

Information about agent key or certificate

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "updateNode"

The id of the action

required
object

Information about the node

Request samples

Content type
application/json
{
  • "properties": [
    ],
  • "policyMode": "audit",
  • "state": "enabled",
  • "agentKey": {
    }
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "updateNode",
  • "data": {
    }
}

Delete a node

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

Authorizations:
path Parameters
nodeId
required
string <uuid (or "root")>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Id of the target node

query Parameters
mode
string
Default: "move"
Enum: "move" "erase"
Example: mode=move

Deletion mode to use, either move to trash ('move', default) or erase ('erase')

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "deleteNode"

The id of the action

required
object

Information about the node

Request samples

curl --header "X-API-Token: yourToken" --request DELETE https://rudder.example.com/rudder/api/latest/nodes/17dadf50-6056-4c8b-a935-6b97d14b89a7

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "deleteNode",
  • "data": {
    }
}

Trigger an agent run

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

Authorizations:
path Parameters
nodeId
required
string <uuid (or "root")>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Id of the target node

Responses

Response Schema: text/plain
string

Request samples

curl --header "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/nodes/17dadf50-6056-4c8b-a935-6b97d14b89a7\?include=full

Get inherited node properties for a node

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

Authorizations:
path Parameters
nodeId
required
string <uuid (or "root")>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Id of the target node

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "nodeInheritedProperties"

The id of the action

required
Array of objects (node-inherited-properties) [ items ]

Information about the node inherited properties

Request samples

curl --header "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/nodes/17dadf50-6056-4c8b-a935-6b97d14b89a7/inheritedProperties

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "nodeInheritedProperties",
  • "data": [
    ]
}

Inventories

Inventory processing service

Get information about inventory processing queue

Provide information about the current state of the inventory processor

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "queueInformation"

The id of the action

required
object

Information about the service

Request samples

curl --header "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "queueInformation",
  • "data": {
    }
}

Upload an inventory for processing

Upload an inventory to the web application

Authorizations:
Request Body schema: multipart/form-data
file
string <binary>
signature
string <binary>

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "uploadInventory"

The id of the action

data
required
string

Request samples

curl --request POST --header "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/inventories/upload -F "file=@inventory-file" -F "signature=@signature-file"

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "uploadInventory",
  • "data": "Inventory 'file.xml' for Node 'c1bab9fc-bcf6-4d59-a397-84c8e2fc06c0' added to processing queue."
}

Restart inventory watcher

Restart the inventory watcher if necessary

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "fileWatcherRestart"

The id of the action

data
required
string

Request samples

curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/inventories/watcher/restart'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "fileWatcherRestart",
  • "data": "Incoming inventory watcher restarted"
}

Start inventory watcher

Start the inventory watcher if necessary

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "fileWatcherStart"

The id of the action

data
required
string

Request samples

curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/inventories/watcher/start'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "fileWatcherStart",
  • "data": "Incoming inventory watcher started"
}

Stop inventory watcher

Stop the inventory watcher if necessary

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "fileWatcherStop"

The id of the action

data
required
string

Request samples

curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/inventories/watcher/stop'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "fileWatcherStop",
  • "data": "Incoming inventory watcher stopped"
}

Parameters

Global parameters

List all global parameters

Get the current value of all the global parameters

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "listParameters"

The id of the action

required
object

Parameters

Request samples

curl --header "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/parameters

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "listParameters",
  • "data": {
    }
}

Create a new parameter

Create a new global parameter

Authorizations:
Request Body schema: application/json
id
required
string

Name of the parameter

value
any <string or JSON>

Value of the parameter

description
string

Description of the parameter

overridable
boolean

Is the global parameter overridable by node

Responses

Response Schema: application/json
id
required
string

Id of the parameter

result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "createParameter"

The id of the action

required
object

Parameters

Request samples

Content type
application/json
{
  • "id": "rudder_file_edit_footer",
  • "value": "### End of file managed by Rudder ###",
  • "description": "Default inform message put in footer of managed files by Rudder",
  • "overridable": false
}

Response samples

Content type
application/json
{
  • "id": "rudder_file_edit_footer",
  • "result": "success",
  • "action": "createParameter",
  • "data": {
    }
}

Get the value of a parameter

Get the current value of a given parameter

Authorizations:
path Parameters
parameterId
required
string
Example: rudder_file_edit_header

Id of the parameter to manage

Responses

Response Schema: application/json
id
required
string

Id of the parameter

result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "parameterDetails"

The id of the action

required
object

Parameters

Request samples

curl --header "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/parameters/ParameterId

Response samples

Content type
application/json
{
  • "id": "rudder_file_edit_footer",
  • "result": "success",
  • "action": "parameterDetails",
  • "data": {
    }
}

Update a parameter's value

Update the properties of a parameter

Authorizations:
path Parameters
parameterId
required
string
Example: rudder_file_edit_header

Id of the parameter to manage

Responses

Response Schema: application/json
id
required
string

Id of the parameter

result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "updateParameter"

The id of the action

required
object

Parameters

Request samples

curl --header "X-API-Token: yourToken" --request POST https://rudder.example.com/rudder/api/latest/parameters/ParameterId --data "value=### Edited by Rudder ###"

Response samples

Content type
application/json
{
  • "id": "rudder_file_edit_footer",
  • "result": "success",
  • "action": "updateParameter",
  • "data": {
    }
}

Delete a parameter

Delete an existing parameter

Authorizations:
path Parameters
parameterId
required
string
Example: rudder_file_edit_header

Id of the parameter to manage

Responses

Response Schema: application/json
id
required
string

Id of the parameter

result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "deleteParameter"

The id of the action

required
object

Parameters

Request samples

curl --header "X-API-Token: yourToken" --request DELETE https://rudder.example.com/rudder/api/latest/parameters/ParameterId

Response samples

Content type
application/json
{
  • "id": "rudder_file_edit_footer",
  • "result": "success",
  • "action": "deleteParameter",
  • "data": {
    }
}

Settings

Server configuration

List all settings

Get the current value of all the settings

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "getAllSettings"

The id of the action

required
object

Information about the setting

Request samples

curl --header "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/settings

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getAllSettings",
  • "data": {
    }
}

Get allowed networks for a policy server

Get the list of allowed networks for a policy server

Authorizations:
path Parameters
nodeId
required
string <uuid (or "root")>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Policy server ID for which you want to manage allowed networks.

Responses

Response Schema: application/json
id
required
string

Target policy server ID

result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "getAllowedNetworks"

The id of the action

required
object

Information about the allowed_networks settings

Request samples

curl --header "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/settings/allowed_networks/root

Response samples

Content type
application/json
{
  • "id": "root",
  • "result": "success",
  • "action": "getAllowedNetworks",
  • "data": {
    }
}

Set allowed networks for a policy server

Set the list of allowed networks for a policy server

Authorizations:
path Parameters
nodeId
required
string <uuid (or "root")>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Policy server ID for which you want to manage allowed networks.

Request Body schema: application/json
value
object

New value of the allowed networks

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "modifyAllowedNetworks"

The id of the action

id
string

The id of the modified node

required
object

Information about the allowed_networks settings

Request samples

Content type
application/json
{
  • "value": "enforce"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "modifyAllowedNetworks",
  • "id": "string",
  • "data": {
    }
}

Modify allowed networks for a policy server

Add or delete allowed networks for a policy server

Authorizations:
path Parameters
nodeId
required
string <uuid (or "root")>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Policy server ID for which you want to manage allowed networks.

Request Body schema: application/json
object

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "modifySetting"

The id of the action

required
object

Information about the allowed_networks settings

Request samples

Content type
application/json
{
  • "allowed_networks": {
    }
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "modifySetting",
  • "data": {
    }
}

Get the value of a setting

Get the current value of a specific setting

Authorizations:
path Parameters
settingId
required
string
Example: global_policy_mode

Id of the setting to set

Responses

Response Schema: application/json
id
required
string

Id of the setting

result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "getSetting"

The id of the action

required
object

Information about the setting

Request samples

curl --header "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/settings/run_frequency

Response samples

Content type
application/json
{
  • "id": "global_policy_mode",
  • "result": "success",
  • "action": "getSetting",
  • "data": {
    }
}

Set the value of a setting

Set the current value of a specific setting

Authorizations:
path Parameters
settingId
required
string
Example: global_policy_mode

Id of the setting to set

Request Body schema: application/json
value
string

New value of the setting

Responses

Response Schema: application/json
id
required
string

Id of the setting

result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "modifySetting"

The id of the action

required
object

Information about the setting

Request samples

Content type
application/json
{
  • "value": "enforce"
}

Response samples

Content type
application/json
{
  • "id": "global_policy_mode",
  • "result": "success",
  • "action": "modifySetting",
  • "data": {
    }
}

System

Internal components and administration

List archives

List configuration archives

Authorizations:
path Parameters
archiveKind
required
string
Enum: "full" "groups" "rules" "directives" "parameters"
Example: full

Type of archive to make

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Enum: "archiveFull" "archiveGroups" "archiveRules" "archiveDirectives" "archiveParameters"

The kind of the archive

required
object

Request samples

curl --header "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/system/archives/full

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "archiveFull",
  • "data": {
    }
}

Create an archive

Create new archive of the given kind

Authorizations:
path Parameters
archiveKind
required
string
Enum: "full" "groups" "rules" "directives" "parameters"
Example: full

Type of archive to make

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Enum: "archiveFull" "archiveGroups" "archiveRules" "archiveDirectives" "archiveParameters"

The kind of the archive

required
object

Request samples

curl --header "X-API-Token: yourToken" --request POST https://rudder.example.com/rudder/api/latest/system/archives/full

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "archiveFull",
  • "data": {
    }
}

Restore an archive

Restore an archive of the given kind for the given moment

Authorizations:
path Parameters
archiveKind
required
string
Enum: "full" "groups" "rules" "directives" "parameters"
Example: full

Type of archive to make

archiveRestoreKind
required
string
Enum: "latestArchive" "latestCommit" "archive ID"
Example: latestCommit

What archive to restore (latest archive, latest commit in configuration repository, or archive with ID as given by listArchive)

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Enum: "restoreFullLatestArchive" "restoreGroupLatestArchive" "restoreRulesLatestArchive" "restoreDirectivesLatestArchive" "restoreParametersLatestArchive" "restoreFullLatestCommit" "restoreGroupLatestCommit" "restoreRulesLatestCommit" "restoreDirectivesLatestCommit" "restoreParametersLatestCommit" "archiveFullDateRestore" "archiveGroupDateRestore" "archiveRulesDateRestore" "archiveDirectivesDateRestore" "archiveParametersDateRestore"

The kind of the archive

required
object

Request samples

curl --header "X-API-Token: yourToken" --request POST https://rudder.example.com/rudder/api/latest/system/archives/full/restore/latestCommit

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "archirestoreFullLatestCommitveFull",
  • "data": {
    }
}

Get an archive as a ZIP

Get an archive of the given kind as a zip

Authorizations:
path Parameters
archiveKind
required
string
Enum: "full" "groups" "rules" "directives" "parameters"
Example: full

Type of archive to make

commitId
required
string

commit ID of the archive to get as a ZIP file

Responses

Response Schema: application/octet-stream
string <binary>

Request samples

curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/system/archives/full/zip/cad7d5f0729f06d22878b99869b8d43629e05a78 -o full-archive.zip

Get healthcheck

Run and get the result of all checks

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "getHealthcheckResult"

The id of the action

required
Array of objects (check) [ items ]

Request samples

curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/system/healthcheck?prettify=true'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getHealthcheckResult",
  • "data": [
    ]
}

Get server information

Get information about the server version

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "getSystemInfo"

The id of the action

required
object

Information about the service

Request samples

curl --header "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/system/info

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getSystemInfo",
  • "data": {
    }
}

Trigger batch for cleaning unreferenced software

Start the software cleaning batch asynchronously.

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "purgeSoftware"

The id of the action

data
required
Array of strings

Request samples

curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/system/maintenance/purgeSoftware?prettify=true'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "purgeSoftware",
  • "data": [
    ]
}

Trigger a new policy generation

Trigger a full policy generation

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "regeneratePolicies"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/system/regenerate/policies'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "regeneratePolicies",
  • "data": {
    }
}

Reload both techniques and dynamic groups

Reload both techniques and dynamic groups

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "reloadAll"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/system/reload'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "reloadAll",
  • "data": {
    }
}

Reload dynamic groups

Reload dynamic groups

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "reloadGroups"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/system/reload/groups'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "reloadGroups",
  • "data": {
    }
}

Reload techniques

Reload techniques from local technique library

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "reloadTechniques"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/system/reload/techniques'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "reloadTechniques",
  • "data": {
    }
}

Get server status

Get information about current server status

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "getStatus"

The id of the action

required
object

Status of the service

Request samples

curl --header "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/system/status

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getStatus",
  • "data": {
    }
}

Trigger update of policies

Update configuration policies if needed

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "updatePolicies"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/system/update/policies'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "updatePolicies",
  • "data": {
    }
}

🧩 Change requests

Requires that the changes-validation plugin is installed on the server.

Manage change requests.

List all change requests

List all change requests

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "listChangeRequests"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/changeRequests --data "status=open"

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "listChangeRequests",
  • "data": {
    }
}

Get a change request details

Get a change request details

Authorizations:
path Parameters
changeRequestId
required
integer
Example: 37

Change request id

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "changeRequestDetails"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/changeRequests --data "status=open"

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "changeRequestDetails",
  • "data": {
    }
}

Decline a request details

Refuse a change request

Authorizations:
path Parameters
changeRequestId
required
integer
Example: 37

Change request id

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "declineChangeRequest"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request DELETE https://rudder.example.com/rudder/api/latest/changeRequests/43

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "declineChangeRequest",
  • "data": {
    }
}

Update a request details

Update a change request

Authorizations:
path Parameters
changeRequestId
required
integer
Example: 37

Change request id

Request Body schema: application/json
name
string

Change request name

description
string

Change request description

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "updateChangeRequest"

The id of the action

required
object

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "updateChangeRequest",
  • "data": {
    }
}

Accept a request details

Accept a change request

Authorizations:
path Parameters
changeRequestId
required
integer
Example: 37

Change request id

Request Body schema: application/json
status
string
Enum: "pending deployment" "deployed"

New status of the change request

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "acceptChangeRequest"

The id of the action

required
object

Request samples

Content type
application/json
{
  • "status": "deployed"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "acceptChangeRequest",
  • "data": {
    }
}

List user

List all validated and unvalidated users

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "listUsers"

The id of the action

required
Array of objects (validated-user) [ items ]

Request samples

curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/users

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "listUsers",
  • "data": [
    ]
}

Update validated user list

Add and remove user from validated users

Authorizations:
Request Body schema: application/json
validatedUsers
required
Array of strings

list of user to put in validated list

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "addUser"

The id of the action

required
object (validated-user)

list of users with their workflow settings

Request samples

Content type
application/json
{
  • "validatedUsers": [
    ]
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "addUser",
  • "data": {
    }
}

Remove an user from validated user list

The user is again subject to workflow validation

Authorizations:
path Parameters
username
required
string
Example: JaneDoe

Username of an user (unique)

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "listUsers"

The id of the action

data
required
string

the user removed from validated list

Request samples

curl --header "X-API-Token: yourToken" --request DELETE https://rudder.example.com/rudder/api/latest/validatedUsers/John Do

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "listUsers",
  • "data": "John Do"
}

🧩 CVE

Requires that the cve plugin is installed on the server.

Manage CVE plugins data and configuration.

Get all CVE details

Get all CVE details

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "getAllCve"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/cve'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getAllCve",
  • "data": {
    }
}

Trigger a CVE check

Trigger a CVE check

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "checkCVE"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/cve/check'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "checkCVE",
  • "data": {
    }
}

Get CVE check config

Get CVE check config

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "getCVECheckConfiguration"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/cve/check/config'

Response samples

Content type
application/json
{}

Update cve check config

Update cve check config

Authorizations:
Request Body schema: application/json
url
string

Url used to check CVE

apiKey
string

Token used by to contact the API to check CVE

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "updateCVECheckConfiguration"

The id of the action

required
object

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Get last CVE check result

Get last CVE check result

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "getLastCVECheck"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/cve/check/last'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getLastCVECheck",
  • "data": {
    }
}

Get a list of CVE details

Get CVE details, from a list passed a paremeter

Authorizations:
Request Body schema: application/json
cveIds
Array of strings

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "getCVEList"

The id of the action

required
object

Request samples

Content type
application/json
{
  • "cveIds": [
    ]
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getCVEList",
  • "data": {
    }
}

Update CVE database from remote source

Update CVE database from remote source

Authorizations:
Request Body schema: application/json
url
string

Url used to update CVE, will default to one set in config

years
Array of strings

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "updateCVE"

The id of the action

required
object

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "updateCVE",
  • "data": {
    }
}

Update CVE database from file system

Update CVE database from file system

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "readCVEfromFS"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/cve/update/FS'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "readCVEfromFS",
  • "data": {
    }
}

🧩 Data sources

Requires that the datasources plugin is installed on the server.

Data sources plugin configuration.

List all data sources

Get the configuration of all present data sources

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "getAllDataSources"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/datasources'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getAllDataSources",
  • "data": {
    }
}

Create a data source

Create a new data source

Authorizations:
Request Body schema: application/json
id
string

Unique identifier of the data source to create.

name
string

The human readable name of the data source to create.

description
string

Description of the goal of the data source to create.

enabled
boolean

Enable or disable data source.

updateTimeout
integer

Duration in seconds before aborting data source update. The main goal is to prevent never ending requests. If a periodicity if configured, you should set that timeout at a lower value.

object

Parameters to configure when the data source is fetched to update node properties.

object

Define and configure data source type.

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "createDataSource"

The id of the action

required
object

Information about the data sources

Request samples

Content type
application/json
{
  • "id": "test-data-source",
  • "name": "Test data source",
  • "description": "Synchronize example data from the CMDB",
  • "enabled": true,
  • "updateTimeout": 30,
  • "runParameters": {
    },
  • "type": {
    }
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "createDataSource",
  • "data": {
    }
}

Update properties from data sources

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

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "ReloadAllDatasourcesAllNodes"

The id of the action

data
required
string

Request samples

curl --header "X-API-Token: yourToken" --request POST https://rudder.example.com/rudder/api/latest/datasources/reload

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "ReloadAllDatasourcesAllNodes",
  • "data": "Data for all nodes, for all configured data sources are going to be updated"
}

Update properties from data sources

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

Authorizations:
path Parameters
datasourceId
required
string
Example: test-data-source

Id of the data source

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "ReloadOneDatasourceAllNodes"

The id of the action

data
required
string

Request samples

curl --header "X-API-Token: yourToken" --request POST https://rudder.example.com/rudder/api/latest/datasources/reload/datasourceId

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "ReloadOneDatasourceAllNodes",
  • "data": "Data for all nodes, for the 'test-data-source' data source are going to be updated"
}

Get data source configuration

Get the configuration of a data source

Authorizations:
path Parameters
datasourceId
required
string
Example: test-data-source

Id of the data source

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "getDataSource"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/datasources/my-data-source

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getDataSource",
  • "data": {
    }
}

Update a data source configuration

Update the configuration of a data source

Authorizations:
path Parameters
datasourceId
required
string
Example: test-data-source

Id of the data source

Request Body schema: application/json
id
string

Unique identifier of the data source to create.

name
string

The human readable name of the data source to create.

description
string

Description of the goal of the data source to create.

enabled
boolean

Enable or disable data source.

updateTimeout
integer

Duration in seconds before aborting data source update. The main goal is to prevent never ending requests. If a periodicity if configured, you should set that timeout at a lower value.

object

Parameters to configure when the data source is fetched to update node properties.

object

Define and configure data source type.

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "updateDataSource"

The id of the action

required
object

Request samples

Content type
application/json
{
  • "id": "test-data-source",
  • "name": "Test data source",
  • "description": "Synchronize example data from the CMDB",
  • "enabled": true,
  • "updateTimeout": 30,
  • "runParameters": {
    },
  • "type": {
    }
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "updateDataSource",
  • "data": {
    }
}

Delete a data source

Delete a data source configuration

Authorizations:
path Parameters
datasourceId
required
string
Example: test-data-source

Id of the data source

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "deleteDataSource"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request DELETE https://rudder.example.com/rudder/api/latest/datasources/my-data-source

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "deleteDataSource",
  • "data": {
    }
}

Update properties for one node from all data sources

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

Authorizations:
path Parameters
nodeId
required
string <uuid (or "root")>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Id of the target node

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "ReloadAllDatasourcesOneNode"

The id of the action

data
required
string

Request samples

curl --header "X-API-Token: yourToken" --request POST https://rudder.example.com/rudder/api/latest/nodes/17dadf50-6056-4c8b-a935-6b97d14b89a7/fetchData

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "ReloadAllDatasourcesOneNode",
  • "data": "Data for node '4e3336f9-ace8-44d6-8d07-496ff1631b01', for all configured data sources, is going to be updated"
}

Update properties for one node from a data source

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

Authorizations:
path Parameters
nodeId
required
string <uuid (or "root")>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Id of the target node

datasourceId
required
string
Example: test-data-source

Id of the data source

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "ReloadOneDatasourceOneNode"

The id of the action

data
required
string

Request samples

curl --header "X-API-Token: yourToken" --request POST https://rudder.example.com/rudder/api/latest/nodes/nodeId/fetchData/datasourceId

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "ReloadOneDatasourceOneNode",
  • "data": "Data for node '4e3336f9-ace8-44d6-8d07-496ff1631b01', for ' test-data-source' data source, is going to be updated"
}

🧩 Scale out Relay

Requires that the scale-out-relay plugin is installed on the server.

Manage relays.

Promote a node to relay

Promote a node to relay

Authorizations:
path Parameters
nodeId
required
string <uuid (or "root")>
Example: 9a1773c9-0889-40b6-be89-f6504443ac1b

Id of the target node

Responses

Response Schema: application/json
action
required
string
Value: "promoteToRelay"

The id of the action

result
required
string
Enum: "success" "error"

Result of the request

data
required
string

Success or error message

Request samples

curl --header "X-API-Token: yourToken" --request POST --header "Content-Type: application/json" https://rudder.example.com/rudder/api/latest/scaleoutrelay/promote/17dadf50-6056-4c8b-a935-6b97d14b89a7?prettify=true'

Response samples

Content type
application/json
{
  • "action": "promoteToRelay",
  • "result": "success",
  • "data": "17dadf50-6056-4c8b-a935-6b97d14b89a7"
}

🧩 Create Node

Requires that the create-node plugin is installed on the server.

Add new nodes.

Create a new node

Create a new node

Authorizations:
query Parameters
Array of objects (node-add) [ items ]

Description of a node configuration

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "createNodes"

The id of the action

required
object

Request samples

nodes.json:

[
  {
    "id":"378740d3-c4a9-4474-8485-478e7e52db52",
    "hostname":"my.node.hostname.local",
    "status":"accepted",
    "os":{
      "type":"linux",
      "name":"debian",
      "version":"9.5",
      "fullName":"Debian GNU/Linux 9 (stretch)"
    },
    "policyServerId":"root",
    "machineType":"vmware",
    "state":"enabled",
    "policyMode":"enforce",
    "agentKey":{
      "value":"----BEGIN CERTIFICATE---- ...."
    },
    "properties":{
      "tags":[
        "some",
        "tags"
      ],
      "env":"prod",
      "vars":{
        "var1":"value1",
        "var2":"value2"
      }
    },
    "ipAddresses":[
      "192.168.180.90",
      "127.0.0.1"
    ],
    "timezone":{
      "name":"CEST",
      "offset":"+0200"
    }
  }
]

curl --header "X-API-Token: yourToken" --request PUT https://rudder.example.com/rudder/api/latest/createnodes --header "Content-type: application/json" --data @nodes.json

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "createNodes",
  • "data": {
    }
}

🧩 User Management

Requires that the user-management plugin is installed on the server.

Manage users settings and configuration file.

Add user

Add a new user

Authorizations:
Request Body schema: application/json
isPreHahed
boolean
Enum: false true

If you want to provide hashed password set this propertie to true otherwise we will hash the plain password and store the hash

username
string
password
string

this password will be hashed for you if the isPreHashed is set on false

role
Array of strings

Defined user's permissions

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "addUser"

The id of the action

required
object

Request samples

Content type
application/json
{
  • "isPreHahed": false,
  • "username": "John Doe",
  • "password": "passwdWillBeStoredHashed",
  • "role": [
    ]
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "addUser",
  • "data": {
    }
}

List all roles

Get all available roles and their rights

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "getRole"

The id of the action

required
Array of objects[ items ]

Request samples

curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/usermanagement/roles'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getRole",
  • "data": [
    ]
}

Update user's infos

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

Authorizations:
path Parameters
username
required
string
Example: JaneDoe

Username of an user (unique)

Request Body schema: application/json
isPreHahed
boolean
Enum: false true

If you want to provide hashed password set this propertie to true otherwise we will hash the plain password and store the hash

username
string
password
string

this password will be hashed for you if the isPreHashed is set on false

role
Array of strings

Defined user's permissions

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "updateUser"

The id of the action

required
object

Request samples

Content type
application/json
{
  • "isPreHahed": false,
  • "username": "John Doe",
  • "password": "passwdWillBeStoredHashed",
  • "role": [
    ]
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "updateUser",
  • "data": {
    }
}

List all users

Get the list of all present users and their permissions

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "getUserInfo"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/usermanagement/users'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getUserInfo",
  • "data": {
    }
}

Reload user

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

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "reloadUserConf"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/usermanagement/users/reload'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "reloadUserConf",
  • "data": {
    }
}

Delete an user

Delete the user and his permissions

Authorizations:
path Parameters
username
required
string
Example: JaneDoe

Username of an user (unique)

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "deleteUser"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request DELETE 'https://rudder.example.com/rudder/api/latest/usermanagement/Toto'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "deleteUser",
  • "data": {
    }
}

🧩 Branding

Requires that the branding plugin is installed on the server.

Manage web interface customization.

Get branding configuration

Get all web interface customization parameters

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "getBrandingConf"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/branding

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getBrandingConf",
  • "data": {
    }
}

Update web interface customization

change color, logo, label etc.

Authorizations:
Request Body schema: application/json
displayBar
required
boolean

Whether header bar is displayed or not

displayLabel
required
boolean

Whether header bar's label is displayed or not

labelText
required
string

The header bar's label title

required
object (color)
required
object (color)
required
object (logo)
required
object (logo)
displayBarLogin
required
boolean

Whether header bar is displayed in loggin page or not

displayMotd
required
boolean

Whether the message of the day is displayed in loggin page or not

motd
required
string

Message of the day in loggin page

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "updateBRandingConf"

The id of the action

required
object

Request samples

Content type
application/json
{
  • "displayBar": true,
  • "displayLabel": true,
  • "labelText": "Production",
  • "barColor": {
    },
  • "labelColor": {
    },
  • "wideLogo": {
    },
  • "smallLogo": {
    },
  • "displayBarLogin": true,
  • "displayMotd": true,
  • "motd": "Welcome, please sign in:"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "updateBRandingConf",
  • "data": {
    }
}

Reload branding file

Reload the configuration from file

Authorizations:

Responses

Response Schema: application/json
result
required
string
Enum: "success" "error"

Result of the request

action
required
string
Value: "getBrandingConf"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request POST https://rudder.example.com/rudder/api/latest/branding/reload

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getBrandingConf",
  • "data": {
    }
}