Rudder API (16)

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]
14 7.0
  • Secret management
  • Directive tree
  • Improve techniques management
  • Demote a relay
15 7.1
  • Package updates in nodes
16 7.2
  • Create node API included from plugin
  • Configuration archive import/export

Response format

All responses from the API are in the JSON format.

{
  "action": "The name of the called function",
  "id": "The ID of the element you want, if relevant",
  "result": "The result of your action: success or error",
  "data": "Only present if this is a success and depends on the function, it's usually a JSON object",
  "errorDetails": "Only present if this is an error, it contains the error message"
}
  • Success responses are sent with the 200 HTTP (Success) code

  • Error responses are sent with a HTTP error code (mostly 5xx...)

HTTP method

Rudder's REST API is based on the usage of HTTP methods. We use them to indicate what action will be done by the request. Currently, we use four of them:

  • GET: search or retrieve information (get rule details, get a group, ...)

  • PUT: add new objects (create a directive, clone a Rule, ...)

  • DELETE: remove objects (delete a node, delete a parameter, ...)

  • POST: update existing objects (update a directive, reload a group, ...)

Parameters

General parameters

Some parameters are available for almost all API functions. They will be described in this section. They must be part of the query and can't be submitted in a JSON form.

Available for all requests

Field Type Description
prettify boolean
optional
Determine if the answer should be prettified (human friendly) or not. We recommend using this for debugging purposes, but not for general script usage as this does add some unnecessary load on the server side.

Default value: false

Available for modification requests (PUT/POST/DELETE)

Field Type Description
reason string
optional or required
Set a message to explain the change. If you set the reason messages to be mandatory in the web interface, failing to supply this value will lead to an error.

Default value: ""

changeRequestName string
optional
Set the change request name, is used only if workflows are enabled. The default value depends on the 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 surprising behavior, do not put a '/' at the end of an URL: it would be interpreted as '/[empty string parameter]' and redirected to '/index', likely not what you wanted to do.

Sending data for POST/PUT requests

Directly in JSON format

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

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

API Info

Information about API endpoints and versions

List all endoints

List all endpoints and their version

Authorizations:
API-Tokens

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:
API-Tokens
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:
API-Tokens
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": {
    }
}

Status

Is alive check

Check if Rudder is alive

An unauthenticated API to check if Rudder web application is up and running. Be careful: this API does not follow other Rudder's API convention:

  • it is not versioned, so the path is just /api/status;
  • it returns a plain text message.
Authorizations:
API-Tokens

Responses

Response Schema: text/plain
string

Request samples

curl --request GET https://rudder.example.com/rudder/api/status

Compliance

Access compliance data

Global compliance

Get current global compliance of a Rudder server

Authorizations:
API-Tokens
query Parameters
precision
integer
Default: 2
Example: precision=0

Number of digits after comma in compliance percent figures

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:
API-Tokens
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)

precision
integer
Default: 2
Example: precision=0

Number of digits after comma in compliance percent figures

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:
API-Tokens
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)

precision
integer
Default: 2
Example: precision=0

Number of digits after comma in compliance percent figures

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:
API-Tokens
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)

precision
integer
Default: 2
Example: precision=0

Number of digits after comma in compliance percent figures

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:
API-Tokens
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)

precision
integer
Default: 2
Example: precision=0

Number of digits after comma in compliance percent figures

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:
API-Tokens

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:
API-Tokens
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)

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

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:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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:
API-Tokens

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:
API-Tokens
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:
API-Tokens
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)

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

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:
API-Tokens
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:
API-Tokens

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:
API-Tokens
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
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:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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
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:
API-Tokens
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
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 methods

Get all generic methods metadata

Authorizations:
API-Tokens

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/methods

Response samples

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

Reload methods

Reload methods metadata from file system

Authorizations:
API-Tokens

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 POST https://rudder.example.com/rudder/api/latest/methods/reload

Response samples

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

List all techniques

List all technique with their versions

Authorizations:
API-Tokens

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": {
    }
}

Create technique

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

Authorizations:
API-Tokens
Request Body schema: application/json
object (editorTechnique)

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

Content type
application/json
[
  • {
    }
]

Response samples

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

List categories

Get all technique categories

Authorizations:
API-Tokens

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/categories

Response samples

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

Reload techniques

Reload all techniques metadata from file system

Authorizations:
API-Tokens

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 POST https://rudder.example.com/rudder/api/latest/techniques/reload

Response samples

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

List versions

List all techniques version

Authorizations:
API-Tokens

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/versions

Response samples

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

Technique metadata by ID

Get each Technique's versions with their metadata by ID

Authorizations:
API-Tokens
path Parameters
techniqueId
required
string
Example: userManagement

Technique ID

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/foo

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:
API-Tokens
path Parameters
techniqueId
required
string
Example: userManagement

Technique ID

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": {
    }
}

Update technique

Update technique created with technique editor

Authorizations:
API-Tokens
path Parameters
techniqueId
required
string
Example: userManagement

Technique ID

techniqueVersion
required
string
Example: 6.0

Technique version

Request Body schema: application/json
object (editorTechnique)

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

Content type
application/json
[
  • {
    }
]

Response samples

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

Delete technique

Delete a technique from technique editor

Authorizations:
API-Tokens
path Parameters
techniqueId
required
string
Example: userManagement

Technique ID

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: "listTechniques"

The id of the action

required
object

Request samples

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

Response samples

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

Technique metadata by version and ID

Get Technique metadata

Authorizations:
API-Tokens
path Parameters
techniqueId
required
string
Example: userManagement

Technique ID

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: "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/foo/1.0

Response samples

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

List all directives based on a version of a technique

List all directives based on a version of a technique

Authorizations:
API-Tokens
path Parameters
techniqueId
required
string
Example: userManagement

Technique ID

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": {
    }
}

Technique's resources

Get currently deployed resources of a technique

Authorizations:
API-Tokens
path Parameters
techniqueId
required
string
Example: userManagement

Technique ID

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: "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/bar/1.0/resources

Response samples

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

Technique's revisions

Get revisions for given technique

Authorizations:
API-Tokens
path Parameters
techniqueId
required
string
Example: userManagement

Technique ID

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: "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/foo/1.0/revisions

Response samples

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

Groups

Groups management

List all groups

List all groups

Authorizations:
API-Tokens

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:
API-Tokens
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

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:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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:
API-Tokens

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:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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

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": {
    }
}

Create one or several new nodes

Use the provided array of node information to create new nodes

Authorizations:
API-Tokens
Request Body schema: application/json
Array
id
required
string

The Rudder node unique identifier in /opt/rudder/etc/uuid.hive

hostname
required
string

The fully qualified name of the node

status
required
string
Enum: "accepted" "pending"

Target status of the node

required
object (os)
policyServerId
string

The policy server ID for that node. By default, "root"

machineType
required
string
Enum: "vmware" "physical" "vm" "solariszone" "qemu" "xen" "aixlpar" "hyperv" "bsdjail"

The kind of machine for the node (use vm for a generic VM)

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

Node lifecycle state. Can only be specified when status=accepted. If not specified, enable is used

policyMode
string
Enum: "enforce" "audit"

The policy mode for the node. Can only be specified when status=accepted. If not specified, the default (global) mode will be used

object (agent-key)

Information about agent key or certificate

required
Array of objects

Node properties (either set by user or filled by third party sources)

ipAddresses
required
Array of strings

an array of IPs.

object (timezone)

Timezone information of the node.

Responses

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

Result of the request

action
required
string
Value: "createNode"

The id of the action

required
object

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "createNode",
  • "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:
API-Tokens

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

Request samples

curl --header "X-API-Token: yourToken" --request POST 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:
API-Tokens
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

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:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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
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:
API-Tokens
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:
API-Tokens
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" --request POST https://rudder.example.com/rudder/api/latest/nodes/root/applyPolicy

Get inherited node properties for a node

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

Authorizations:
API-Tokens
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)

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:
API-Tokens

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:
API-Tokens
Request Body schema: multipart/form-data
file
string <binary>

The inventory file. The original file name is used to check extension, that should be .xml[.gz] or .ocs[.gz]

signature
string <binary>

The signature file. The original file name is used to check extension, that should be ${originalInventoryFileName}.sign[.gz]

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:
API-Tokens

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:
API-Tokens

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:
API-Tokens

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:
API-Tokens

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:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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": {
    }
}

Archives

Import and export zip of policies

Get a ZIP archive of the requested items and their dependencies

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

Authorizations:
API-Tokens
query Parameters
rules
Array of arrays
Examples:
  • rules=a0573b59-e5bd-441b-9031-f307aa21a61e - Example of a single ID
  • rules=a0573b59-e5bd-441b-9031-f307aa21a61e,4cba6eee-3a43-4e17-a608-a4941b6d984f%2B35177d0823791a374de9e16a6ab27e6466fbc8c2 - Example of multiple IDs, some with revisions

IDs (optionally with revision, '+' need to be escaped as '%2B') of rules to include

rules
Array of arrays
Examples:
  • rules=a0573b59-e5bd-441b-9031-f307aa21a61e - Example of a single ID
  • rules=a0573b59-e5bd-441b-9031-f307aa21a61e,4cba6eee-3a43-4e17-a608-a4941b6d984f%2B35177d0823791a374de9e16a6ab27e6466fbc8c2 - Example of multiple IDs, some with revisions

IDs (optionally with revision, '+' need to be escaped as '%2B') of rules to include

directives
Array of arrays
Examples:
  • directives=a0573b59-e5bd-441b-9031-f307aa21a61e - Example of a single ID
  • directives=a0573b59-e5bd-441b-9031-f307aa21a61e,4cba6eee-3a43-4e17-a608-a4941b6d984f%2B35177d0823791a374de9e16a6ab27e6466fbc8c2 - Example of multiple IDs, some with revisions

IDs (optionally with revision, '+' need to be escaped as '%2B') of directives to include

techniques
Array of arrays
Examples:
  • techniques=fileContent/3.0 - Example of a single ID
  • techniques=userManagement/6.3,fileContent/3.0%2B35177d0823791a374de9e16a6ab27e6466fbc8c2 - Example of multiple IDs, some with revisions

IDs, ie technique name/technique version (optionally with revision, '+' need to be escaped as '%2B') of techniques to include

groups
Array of arrays
Examples:
  • groups=a0573b59-e5bd-441b-9031-f307aa21a61e - Example of a single ID
  • groups=a0573b59-e5bd-441b-9031-f307aa21a61e,4cba6eee-3a43-4e17-a608-a4941b6d984f%2B35177d0823791a374de9e16a6ab27e6466fbc8c2 - Example of multiple IDs, some with revisions

IDs (optionally with revision, '+' need to be escaped as '%2B') of groups to include

include
Array of strings
Items Enum: "all (default)" "none" "directives" "techniques" "groups"
Examples:
  • include=none - Do not include dependencies
  • include=directives,groups - Include directives and groups, but no techniques

Scope of dependencies to include in archive, where rule as directives and groups dependencies, directives have techniques dependencies, and techniques and groups don't have dependencies. 'none' means no dependencies will be include, 'all' means that the whole tree will, 'directives' and 'groups' means to include them specifically, 'techniques' means to include both directives and techniques.

Responses

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

Request samples

curl --header "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/archives/export?rules=8e522a3e-aa45-43cd-bf33-4e8d04a566f6&include=directives,groups

Import a ZIP archive of policies into Rudder

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

Authorizations:
API-Tokens
Request Body schema: multipart/form-data
archive
string <binary>

The ZIP archive file containing policies in a conventional layout and serialization format

Responses

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

Result of the request

action
required
string
Value: "import"

The id of the action

required
object

Details about archive import process

Request samples

curl --header "X-API-Token: yourToken" -X POST https://rudder.example.com/rudder/api/latest/archives/import --form "archive=@my-archive-file.zip"

Response samples

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

Settings

Server configuration

List all settings

Get the current value of all the settings

Authorizations:
API-Tokens

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:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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: "modifyDiffAllowedNetworks"

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": "modifyDiffAllowedNetworks",
  • "data": {
    }
}

Get the value of a setting

Get the current value of a specific setting

Authorizations:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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:
API-Tokens

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)

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:
API-Tokens

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:
API-Tokens

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:
API-Tokens

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:
API-Tokens

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:
API-Tokens

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:
API-Tokens

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:
API-Tokens

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:
API-Tokens

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:
API-Tokens

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:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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:
API-Tokens

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)

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:
API-Tokens
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:
API-Tokens
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:
API-Tokens

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:
API-Tokens

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:
API-Tokens

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:
API-Tokens
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:
API-Tokens
query Parameters
groupId
string

Id of node groups you want to get from last CVE check

nodeId
string

Id of nodes you want to get from last CVE check

cveId
string

Id of CVE you want to get from last CVE check

package
string

Name of packages you want to get from last CVE check

severity
string
Enum: "critical" "high" "medium" "low" "none" "unknown"

Severity of the CVE you want to get from last CVE check

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 as parameter

Authorizations:
API-Tokens
Request Body schema: application/json
cveIds
Array of strings
onlyScore
boolean
Default: false

Only send score of the cve, and not the whole detailed list

minScore
float

Only send CVE with a score higher than the value

maxScore
float

Only send CVE with a score lower than the value

publishedDate
string

Only send CVE with a publication date more recent than the value

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": [
    ],
  • "onlyScore": true,
  • "minScore": 7.5,
  • "maxScore": 8.5,
  • "publishedDate": "string"
}

Response samples

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

Update CVE database from remote source

Update CVE database from remote source

Authorizations:
API-Tokens
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:
API-Tokens

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": {
    }
}

Get a CVE details

Get a CVE details

Authorizations:
API-Tokens
path Parameters
cveId
required
string <uuid>
Example: CVE-2022-25235

Id of the CVE

Responses

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

Result of the request

action
required
string
Value: "getCve"

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/CVE-2019-5953'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getCve",
  • "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:
API-Tokens

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:
API-Tokens
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:
API-Tokens

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:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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:
API-Tokens
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.

Demote a relay to simple node

Demote a relay to a simple node.

Authorizations:
API-Tokens
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: "demoteToNode"

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": "demoteToNode",
  • "result": "success",
  • "data": "17dadf50-6056-4c8b-a935-6b97d14b89a7"
}

Promote a node to relay

Promote a node to relay

Authorizations:
API-Tokens
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"
}

🧩 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:
API-Tokens
Request Body schema: application/json
isPreHahed
boolean
Enum: false true

If you want to provide hashed password set this property 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:
API-Tokens

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

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:
API-Tokens
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 property 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:
API-Tokens

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:
API-Tokens

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:
API-Tokens
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:
API-Tokens

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:
API-Tokens
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 login page or not

displayMotd
required
boolean

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

motd
required
string

Message of the day in login 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:
API-Tokens

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": {
    }
}

🧩 Secret Management

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

Manage secrets variables.

List all secrets

Get the list of all secrets without their value

Authorizations:
API-Tokens

Responses

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

Result of the request

action
required
string
Value: "getAllSecrets"

The id of the action

required
object

Request samples

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

Response samples

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

Update a secret

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

Authorizations:
API-Tokens
Request Body schema: application/json
name
string

The name of the secret used as a reference on the value

description
string

The description of the secret to identify it more easily

value
string

The value of the secret it will not be exposed in the interface

Responses

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

Result of the request

action
required
string
Value: "updateSecret"

The id of the action

required
object

Request samples

Content type
application/json
{
  • "name": "secret-password",
  • "description": "Password of my super secret user account",
  • "value": "nj-k;EO32!kFWewn2Nk,u"
}

Response samples

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

Create a secret

Add a secret

Authorizations:
API-Tokens
Request Body schema: application/json
name
string

The name of the secret used as a reference on the value

description
string

The description of the secret to identify it more easily

value
string

The value of the secret it will not be exposed in the interface

Responses

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

Result of the request

action
required
string
Value: "addSecret"

The id of the action

required
object

Request samples

Content type
application/json
{
  • "name": "secret-password",
  • "description": "Password of my super secret user account",
  • "value": "nj-k;EO32!kFWewn2Nk,u"
}

Response samples

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

Get one secret

Get one secret by his unique name

Authorizations:
API-Tokens
path Parameters
name
required
string

Unique name of the secret

Responses

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

Result of the request

action
required
string
Value: "getSecret"

The id of the action

required
object

Request samples

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

Response samples

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

Delete a secret

Remove the secret by his unique name

Authorizations:
API-Tokens
path Parameters
name
required
string

Unique name of the secret

Responses

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

Result of the request

action
required
string
Value: "deleteSecret"

The id of the action

required
object

Request samples

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

Response samples

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