Rudder API (18)

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

Download OpenAPI specification: openapi.yml

Other documentation sources:

Introduction

Rudder exposes a REST API, enabling the user to interact with Rudder without using the webapp, for example, in scripts or cron jobs.

Authentication

The Rudder REST API uses simple API keys for authentication. All requests must be authenticated (except from a generic status API). The tokens are 32-character strings, passed in a X-API-Token header, like in:

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

The tokens are the API equivalent of a password, and must be secured just like a password would be.

API accounts

The accounts are managed in the Web interface. There are two possible types of accounts:

  • Global API accounts: they are not linked to a Rudder user, and are managed by Rudder administrators in the Administration -> API accounts page. You should define an expiration date whenever possible.

General API tokens settings

  • User tokens: they are linked to a Rudder user, and give the same rights the user has. There can be only one token by user. This feature is provided by the api-authorizatons plugin.

User API token

When an action produces a change of configuration on the server, the API account that made it will be recorded in the event log, like for a Web interaction.

Authorization

When using Rudder without the api-authorizatons plugin, only global accounts are available, with two possible privilege levels, read-only or write. With the api-authorizatons plugin, you also get access to:

  • User tokens, which have the same permissions as the user, using the Rudder roles and permissions feature.
  • Custom ACLs on global API accounts. They provide fine-grained permissions on every endpoint:

Custom API ACL

As a general principle, you should create dedicated tokens with the least privilege level for each different interaction you have with the API. This limits the risks of exploitation if a token is stolen, and allows tracking the activity of each token separately. Token renewal is also easier when they are only used for a limited purpose.

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
17 7.3
  • Compliance by directive
  • Path campaigns API included
18 8.0
  • Allowed network
  • Improve the structure of `/settings/allowed_networks` output

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 a 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 endpoints

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.

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 directives

Get current compliance of all the nodes of a Rudder server

Authorizations:
API-Tokens

Responses

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

Result of the request

action
required
string
Value: "getDirectiveComplianceId"

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/directives'

Response samples

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

Compliance details by directive

Get current compliance of a directive of a Rudder server

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

Id of the directive

query Parameters
format
string
Examples:
  • format=csv - CSV format for the export

format of export

Responses

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

Result of the request

action
required
string
Value: "getDirectiveComplianceId"

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/directives/704afe7b-1a65-4d2e-b4c9-54f4f548c316'

Response samples

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

Compliance details by group (global)

Get compliance of a group with all rules that apply to a node within the group.

Authorizations:
API-Tokens
path Parameters
required
string or rule-target (string)

Id of the node group or rule target

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

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/groups/704afe7b-1a65-4d2e-b4c9-54f4f548c316'

Response samples

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

Compliance details by group (targeted)

Get compliance of a group with only rules that explicitly include the group.

Authorizations:
API-Tokens
path Parameters
required
string or rule-target (string)

Id of the node group or rule target

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

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/groups/704afe7b-1a65-4d2e-b4c9-54f4f548c316/target'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getNodeGroupComplianceTargetId",
  • "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
required
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
required
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
required
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
required
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
required
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
required
Array
id
string

Technique id

name
string

Technique name

version
string

version of this technique

category
string

category of this technique

description
string

description of this technique

source
string

Source of the technique, always editor here

Array of objects (technique-parameter)

Parameters for this technique

Array of objects (technique-resource)

Resources for this technique

Array of technique-method-call (object) or technique-block (object)

Method and blocks contained by this technique

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
required
Array
id
string

Technique id

name
string

Technique name

version
string

version of this technique

category
string

category of this technique

description
string

description of this technique

source
string

Source of the technique, always editor here

Array of objects (technique-parameter)

Parameters for this technique

Array of objects (technique-resource)

Resources for this technique

Array of technique-method-call (object) or technique-block (object)

Method and blocks contained by this technique

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
required
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
required
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
required
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, softwareUpdate, 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
required
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
string
Enum: "physical" "vm" "aixlpar" "bsdjail" "hyperv" "qemu" "solariszone" "vbox" "vmware" "xen"

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

object

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, softwareUpdate, 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, softwareUpdate, 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 properties

List all global properties

Get the current value of all the global properties (a.k.a. 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 property

Create a new global property

Authorizations:
API-Tokens
Request Body schema: application/json
required
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 property

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 global property

Get the current value of a given global property (a.k.a. global 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 property

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 global property's value

Update the details of a global property

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 global property

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

Delete an existing global 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 global property

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

Campaigns

Campaigns

Get all campaigns details

Get all campaigns details

Authorizations:
API-Tokens
query Parameters
campaignType
string
Enum: "system-update" "software-update"
Example: campaignType=system-update

Type of the campaigns we want

status
string
Enum: "enabled" "disabled" "archived"
Example: status=enabled

Status of the campaigns we want

Responses

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

Result of the request

action
required
string
Value: "allCampaigns"

The id of the action

required
object

Request samples

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

Response samples

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

Save a campaign

Save a campaign details

Authorizations:
API-Tokens
Request Body schema: application/json
required
object

common data about campaign

campaignType
string
Enum: "system-update" "software-update"

Type of campaign (with version determine what kind of campaign you handle and the details object)

version
integer

Version of campaign (with type determine what kind of campaign you handle and the details object)

campaign-system-update (object) or campaign-software-update (object)

Responses

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

Result of the request

action
required
string
Value: "saveCampaign"

The id of the action

required
object

Request samples

Content type
application/json
{
  • "info": {
    },
  • "campaignType": "system-update",
  • "version": 2,
  • "details": {
    }
}

Response samples

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

Get all campaign events

Get all campaign events

Authorizations:
API-Tokens
query Parameters
campaignType
string
Enum: "system-update" "software-update"
Example: campaignType=system-update

Type of the campaigns we want

state
string
Enum: "scheduled" "running" "finished" "skipped"
Example: state=enabled

Status of the campaign events we want

campaignId
string
Enum: "system-update" "software-update"
Example: campaignId=system-update

id of the campaigns we want

limit
integer

Max number of elements in response

offset
integer

Offset of data in response (skip X elements)

before
string <date>
after
string <date>
order
string
asc
string
Enum: "asc" "desc"

Responses

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

Result of the request

action
required
string
Value: "getCampaignEvent"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/campaigns/0076a379-f32d-4732-9e91-33ab219d8fde/events'

Response samples

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

Get a campaign event details

Get a campaign event details

Authorizations:
API-Tokens
path Parameters
id
required
string <uuid>
Example: 0076a379-f32d-4732-9e91-33ab219d8fde

Id of the campaign event

Responses

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

Result of the request

action
required
string
Value: "getCampaignEvent"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/campaigns/events/0076a379-f32d-4732-9e91-33ab219d8fde'

Response samples

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

Update an existing event

Update an existing event

Authorizations:
API-Tokens
path Parameters
id
required
string <uuid>
Example: 0076a379-f32d-4732-9e91-33ab219d8fde

Id of the campaign event

Responses

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

Result of the request

action
required
string
Value: "saveCampaignEvent"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/campaigns/events/0076a379-f32d-4732-9e91-33ab219d8fde'

Response samples

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

Delete a campaign event details

Delete a campaign event details

Authorizations:
API-Tokens
path Parameters
id
required
string <uuid>
Example: 0076a379-f32d-4732-9e91-33ab219d8fde

Id of the campaign event

Responses

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

Result of the request

action
required
string
Value: "deleteCampaignEvent"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request DELETE 'https://rudder.example.com/rudder/api/latest/campaigns/events/0076a379-f32d-4732-9e91-33ab219d8fde'

Response samples

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

Get a campaign details

Get a campaign details

Authorizations:
API-Tokens
path Parameters
id
required
string <uuid>
Example: 0076a379-f32d-4732-9e91-33ab219d8fde

Id of the campaign

Responses

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

Result of the request

action
required
string
Value: "getCampaign"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/campaigns/0076a379-f32d-4732-9e91-33ab219d8fde'

Response samples

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

Delete a campaign

Delete a campaign

Authorizations:
API-Tokens
path Parameters
id
required
string <uuid>
Example: 0076a379-f32d-4732-9e91-33ab219d8fde

Id of the campaign

Responses

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

Result of the request

action
required
string
Value: "deleteCampaign"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request DELETE 'https://rudder.example.com/rudder/api/latest/campaigns/0076a379-f32d-4732-9e91-33ab219d8fde'

Response samples

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

Get campaign events for a campaign

Get campaign events for a campaign

Authorizations:
API-Tokens
path Parameters
id
required
string <uuid>
Example: 0076a379-f32d-4732-9e91-33ab219d8fde

Id of the campaign

query Parameters
campaignType
string
Enum: "system-update" "software-update"
Example: campaignType=system-update

Type of the campaigns we want

state
string
Enum: "scheduled" "running" "finished" "skipped"
Example: state=enabled

Status of the campaign events we want

limit
integer

Max number of elements in response

offset
integer

Offset of data in response (skip X elements)

before
string <date>
after
string <date>
order
string
asc
string
Enum: "asc" "desc"

Responses

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

Result of the request

action
required
string
Value: "getEventsCampaign"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/campaigns/0076a379-f32d-4732-9e91-33ab219d8fde/events'

Response samples

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

Schedule a campaign event for a campaign

Schedule a campaign event for a campaign

Authorizations:
API-Tokens
path Parameters
id
required
string <uuid>
Example: 0076a379-f32d-4732-9e91-33ab219d8fde

Id of the campaign

Responses

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

Result of the request

action
required
string
Value: "scheduleCampaign"

The id of the action

required
object

Request samples

curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/campaigns/0076a379-f32d-4732-9e91-33ab219d8fde/schedule'

Response samples

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

merge
string
Enum: "override-all" "keep-rule-groups"

Optional merge algo of the import. Default override-all means what is in the archive is the new reality. keep-rule-groups will keep existing target definition for existing rules (ignore archive value).

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" --form "merge=keep-rule-groups"

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
required
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
required
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
required
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
required
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
required
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
required
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
string <A score between 0 and 10 as a float>

Only send CVE with a score higher than the value

maxScore
string <A score between 0 and 10 as a float>

Only send CVE with a score lower than the value

publishedDate
string <date>

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": "2019-08-24"
}

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

🧩 System update campaigns

Requires that the system update plugin is installed on the server.

Fetch System update campaigns results.

Get a campaign result history

Get a campaign result history

Authorizations:
API-Tokens
path Parameters
id
required
string <uuid>
Example: 0076a379-f32d-4732-9e91-33ab219d8fde

Id of the campaign

query Parameters
limit
integer

Max number of elements in response

offset
integer

Offset of data in response (skip X elements)

before
string <date>
after
string <date>
order
string
asc
string
Enum: "asc" "desc"

Responses

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

Result of the request

action
required
string
Value: "getCampaignResults"

The id of the action

required
object

Request samples

curl --silent --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/systemUpdate/campaign/0076a379-f32d-4732-9e91-33ab219d8fde/history'

Response samples

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

Get a campaign event result

Get a campaign event result

Authorizations:
API-Tokens
path Parameters
id
required
string <uuid>
Example: 0076a379-f32d-4732-9e91-33ab219d8fde

Id of the campaign event

Responses

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

Result of the request

action
required
string
Value: "getCampaignEventResult"

The id of the action

id
string <uuid>

Campaign event id

required
object

Request samples

curl --silent --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/systemUpdate/events/0076a379-f32d-4732-9e91-33ab219d8fde/result'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getCampaignEventResult",
  • "id": "0076a379-f32d-4732-9e91-33ab219d8fde",
  • "data": {
    }
}

Get detailed campaign event result for a Node

Get detailed campaign event result for a Node

Authorizations:
API-Tokens
path Parameters
id
required
string <uuid>
Example: 0076a379-f32d-4732-9e91-33ab219d8fde

Id of the campaign event

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

The id of the action

id
string <uuid>

Campaign event id

required
object

Request samples

curl --silent --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/systemUpdate/events/0076a379-f32d-4732-9e91-33ab219d8fde/result/b81d08e8-03f8-46b7-9399-9bea54e41ec7'

Response samples

Content type
application/json
{
  • "result": "success",
  • "action": "getSystemUpdateResultForNode",
  • "id": "0076a379-f32d-4732-9e91-33ab219d8fde",
  • "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
required
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
required
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 their 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
required
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
required
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
required
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 its 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 its 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": {
    }
}

🧩 OpenSCAP

Requires that the openscap plugin is installed on the server.

Get OpenSCAP reports for nodes.

Get an OpenSCAP report

Get latest OpenSCAP report for the given 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/html
string <HTML>

Request samples

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

🧩 Multi-tenants

Requires that the multitenants plugin is installed on the server.

Manage tenants and set them on nodes.

Tenants

Define a tenant on nodes

Set given tenant to the list of nodes. You can give several (tenantId, nodes) in one go.

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

the ID of the tenant to set on nodes

nodeIds
required
Array of strings

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

Content type
application/json
[
  • {
    }
]

Response samples

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

Get the list of all tenants.

Get the list of tenants. The special '*' and '-' are not included in the returned values.

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

Response samples

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

Add one or more tenants

Add one or more tenants to existing list. Already defined tenants (same id) are updated

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

A unique identifier for a tenant, matching ^(\p{Alnum}[\p{Alnum}-_]*)$

name
string

A name for humans

description
string

One line description of the tenant, typically used to get a glimpse of tenant goal.

documentation
string

A long form description of the tenant, accepting markdown

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
[
  • {
    }
]

Response samples

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

Delete a list of tenants

Delete the list of tenants with given IDs

Authorizations:
API-Tokens

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/tenants' --data '["zone1","zone2"]'

Response samples

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

Get tenant details

Get detailed information about one tenant

Authorizations:
API-Tokens
path Parameters
id
required
string <string matching ^(\p{Alnum}[\p{Alnum}-_]*)$>
Example: zone-1

Id of the tenant

Responses

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

Result of the request

action
required
string
Value: "getTenant"

The id of the action

required
object

Request samples

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

Response samples

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