{ "swagger": "2.0", "info": { "contact": { "email": "dev@rudder.io", "name": "Rudder developers", "url": "https://www.rudder.io" }, "description": "Download OpenAPI specification: [openapi.yml](openapi.yml)\n\n# Introduction\n\nRudder exposes a REST API, enabling the user to interact with Rudder without using the webapp, for example in scripts or cronjobs.\n\n## Versioning\n\nEach 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\nto 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`.\n\nYou can change the version of the API used by setting it either within the url or in a header:\n\n* the URL: each URL is prefixed by its version id, like `/api/version/function`.\n\n\n # Version 10\n curl -X GET -H \"X-API-Token: yourToken\" https://rudder.example.com/rudder/api/10/rules\n # Latest\n curl -X GET -H \"X-API-Token: yourToken\" https://rudder.example.com/rudder/api/latest/rules\n # Wrong (not an integer) => 404 not found\n curl -X GET -H \"X-API-Token: yourToken\" https://rudder.example.com/rudder/api/3.14/rules\n\n\n* the HTTP headers. You can add the **X-API-Version** header to your request. The value needs to be an integer or `latest`.\n\n\n # Version 10\n curl -X GET -H \"X-API-Token: yourToken\" -H \"X-API-Version: 10\" https://rudder.example.com/rudder/api/rules\n # Wrong => Error response indicating which versions are available\n curl -X GET -H \"X-API-Token: yourToken\" -H \"X-API-Version: 3.14\" https://rudder.example.com/rudder/api/rules\n\n\nIn 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\nperiod of time to allow migration from previous versions.\n\n\n

Existing versions

\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n \n
VersionRudder versions it appeared inDescription
1Never released (for internal use only)Experimental version
2 to 10 (deprecated)4.3 and beforeThese versions provided the core set of API features for rules, directives, nodes global parameters, change requests and compliance, rudder settings and system API
115.0New system API (replacing old localhost v1 api): status, maintenance operations and server behavior
126.0Node key management
\n\n\n## Response format\n\nAll responses from the API are in the JSON format.\n\n\n {\n \"action\": The name of the called function,\n \"id\": The ID of the element you want, if relevant,\n \"result\": The result of your action: success or error,\n \"data\": Only present if this is a success and depends on the function, it's usually a JSON object,\n \"errorDetails\": Only present if this is an error, it contains the error message\n }\n\n\n\n* __Success__ responses are sent with the 200 HTTP (Success) code\n\n* __Error__ responses are sent with a HTTP error code (mostly 5xx...)\n\n\n## HTTP method\n\nRudder's REST API is based on the usage of [HTTP methods](http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html). We use them to indicate what action will be done by the request. Currently, we use four of them:\n\n\n* **GET**: search or retrieve information (get rule details, get a group, ...)\n\n* **PUT**: add new objects (create a directive, clone a Rule, ...)\n\n* **DELETE**: remove objects (delete a node, delete a parameter, ...)\n\n* **POST**: update existing objects (update a directive, reload a group, ...)\n\n\n## Parameters\n\nTo use Rudder API, you may need to pass data attributes to the API. Most of them depends on the called function and will be described below, in the corresponding function's section. Some are common to almost all functions and are described here:\n\n### Passing parameters\n\nParameters to the API can be sent:\n\n\n* As part of the URL\n\n* As request arguments\n\n* Directly in JSON format\n\n\n#### As part of the URL\n\nParameters in URLs are used to indicate which data you want to interact with. The function will not work if this data is missing.\n\n\n # Get the Rule of ID \"id\"\n curl -H \"X-API-Token: yourToken\" https://rudder.example.com/rudder/api/latest/rules/id\n\n\n#### Request parameters\n\nIn most cases, data will be sent using request parameters. for all data you want to change, you need to pass one parameter.\n\nParameters follow the following schema:\n\n\n key=value\n\n\nYou can pass parameters by two means:\n\n* As query parameters: At the end of your url, put a **?** then your first parameter and then a **&** before next parameters\n\n\n # Update the Rule 'id' with a new name, disabled, and setting it one directive \n 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\"\n\n\n* 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.\n\n\n # Update the Rule 'id' with a new name, disabled, and setting it one directive (in file directive-info.json)\n curl -X POST -H \"X-API-Token: yourToken\"\n https://rudder.example.com/rudder/api/rules/latest/{id} -d \"displayName=my new name\" -d \"enabled=false\" -d @directive-info.json\n\n\n#### Directly in JSON format\n\nInstead of passing parameters one by one, you can instead supply a JSON object containing all you want to do. You'll also have to set the *Content-Type* header to **application/json** (without it the JSON content would be ignored).\n\nThe supplied file must contain a valid JSON: strings need quotes, booleans and integers\ndon't, ...\n\nThe (human readable) format is:\n\n\n {\n \"key1\": \"value1\",\n \"key2\": false,\n \"key3\": 42\n }\n\n\nHere is an example with inlined data:\n\n\n\n # Update the Rule 'id' with a new name, disabled, and setting it one directive\n curl -X POST -H \"X-API-Token: yourToken\" -H \"Content-Type: application/json\"\n https://rudder.example.com/rudder/api/rules/latest/{id} \n -d '{ \"displayName\": \"new name\", \"enabled\": false, \"directives\": \"directiveId\"}'\n\n\n\nYou can also pass a supply the JSON in a file:\n\n\n # Update the Rule 'id' with a new name, disabled, and setting it one directive \n curl -X POST -H \"X-API-Token: yourToken\" -H \"Content-Type: application/json\" https://rudder.example.com/rudder/api/rules/latest/{id} -d @jsonParam\n\n\nNote that some parameters cannot be passed in a JSON (general parameters, it will be precised when necessary), 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)\n\n\n # Update the Rule 'id' with a new name, disabled, and setting it one directive with reason message \"Reason used\" \n 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\"\n\n\n### General parameters\n\nSome parameters are available for almost all API functions. They will be described in this section.\nThey must be part of the query and can't be submitted in a JSON form.\n\n#### Available for all requests\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
FieldTypeDescription
prettifyboolean
optional		\n 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.\n

Default value: false

\n
\n\n\n#### Available for modification requests (PUT/POST/DELETE)\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
FieldTypeDescription
reasonstring
optional or required		\n 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.\n

Default value: \"\"

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

Default value: A default string for each function

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

Default value: \"\"

\n
\n", "license": { "name": "CC-BY-SA 2.0", "url": "https://spdx.org/licenses/CC-BY-SA-2.0.html" }, "title": "Rudder API", "version": "12", "x-apisguru-categories": [ "developer_tools" ], "x-logo": { "url": "https://api.apis.guru/v2/cache/logo/https_www.rudder.io_wp-content_uploads_2019_11_color_logo_horizontal_dark_bg-1024x176.png" }, "x-origin": [ { "format": "openapi", "url": "https://docs.rudder.io/api/openapi.yml", "version": "3.0" } ], "x-preferred": true, "x-providerName": "rudder.example.local", "x-datafire": { "name": "rudder_example_local", "type": "openapi" } }, "host": "rudder.example.local", "basePath": "/rudder/api/latest/", "schemes": [ "https" ], "paths": { "/api/changeRequests": { "get": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Change requests information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "listChangeRequests" ], "type": "string" }, "data": { "properties": { "rules": { "items": { "$ref": "#/definitions/change-request" }, "type": "array" } }, "required": [ "rules" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 Change requests" ], "description": "List all change requests", "operationId": "listChangeRequests", "summary": "List all change requests", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET https://rudder.example.com/rudder/api/latest/changeRequests --data \"status=open\"\n" } ] } }, "/branding": { "get": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Branding configuration", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "getBrandingConf" ], "type": "string" }, "data": { "properties": { "branding": { "$ref": "#/definitions/branding-conf" } }, "required": [ "branding" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 Branding" ], "description": "Get all web interface customization parameters", "operationId": "getBrandingConf", "summary": "Get branding configuration", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET https://rudder.example.com/rudder/api/latest/branding\n" } ] }, "post": { "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "parameters": [ { "in": "formData", "name": "barColor", "required": true, "type": "object" }, { "description": "Whether header bar is displayed or not", "in": "formData", "name": "displayBar", "required": true, "type": "boolean" }, { "description": "Whether header bar is displayed in loggin page or not", "in": "formData", "name": "displayBarLogin", "required": true, "type": "boolean" }, { "description": "Whether header bar's label is displayed or not", "in": "formData", "name": "displayLabel", "required": true, "type": "boolean" }, { "description": "Whether the message of the day is displayed in loggin page or not", "in": "formData", "name": "displayMotd", "required": true, "type": "boolean" }, { "in": "formData", "name": "labelColor", "required": true, "type": "object" }, { "description": "The header bar's label title", "in": "formData", "name": "labelText", "required": true, "type": "string" }, { "description": "Message of the day in loggin page", "in": "formData", "name": "motd", "required": true, "type": "string" }, { "in": "formData", "name": "smallLogo", "required": true, "type": "object" }, { "in": "formData", "name": "wideLogo", "required": true, "type": "object" } ], "responses": { "200": { "description": "Updated", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "updateBRandingConf" ], "type": "string" }, "data": { "properties": { "branding": { "$ref": "#/definitions/branding-conf" } }, "required": [ "branding" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 Branding" ], "description": "change color, logo, label etc.", "operationId": "updateBRandingConf", "summary": "Update web interface customization", "x-code-samples": [ { "lang": "curl", "source": "update.json:\n\n{\n\t\"displayBar\":true,\n\t\"displayLabel\":false,\n\t\"labelText\":\"Production\",\n\t\"barColor\":{\n\t\t\"red\":1,\n\t\t\"blue\":1,\n\t\t\"green\":1,\n\t\t\"alpha\":1\n\t},\n\t\"labelColor\":{\n\t\t\"red\":0,\n\t\t\"blue\":0,\n\t\t\"green\":0,\n\t\t\"alpha\":1\n\t},\n\t\"wideLogo\":{\n\t\t\"enable\":true\n\t},\n\t\"smallLogo\":{\n\t\t\"enable\":true\n\t},\n\t\"displayBarLogin\":true,\n\t\"displayMotd\":true,\n\t\"motd\":\"Welcome, please sign in:\"\n}\n\ncurl --header \"X-API-Token: yourToken\" --request POST https://rudder.example.com/rudder/api/latest/branding --header \"Content-type: application/json\" --data @update.json\n\n" } ] } }, "/branding/reload": { "post": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Branding configuration", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "getBrandingConf" ], "type": "string" }, "data": { "properties": { "branding": { "$ref": "#/definitions/branding-conf" } }, "required": [ "branding" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 Branding" ], "description": "Reload the configuration from file", "operationId": "reloadBrandingConf", "summary": "Reload branding file", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST https://rudder.example.com/rudder/api/latest/branding/reload\n" } ] } }, "/changeRequests/{changeRequestId}": { "delete": { "produces": [ "application/json" ], "parameters": [ { "description": "Change request id", "in": "path", "name": "changeRequestId", "required": true, "type": "integer" } ], "responses": { "200": { "description": "Change requests information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "declineChangeRequest" ], "type": "string" }, "data": { "properties": { "rules": { "items": { "$ref": "#/definitions/change-request" }, "type": "array" } }, "required": [ "rules" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 Change requests" ], "description": "Refuse a change request", "operationId": "declineChangeRequest", "summary": "Decline a request details", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request DELETE https://rudder.example.com/rudder/api/latest/changeRequests/43" } ] }, "get": { "produces": [ "application/json" ], "parameters": [ { "description": "Change request id", "in": "path", "name": "changeRequestId", "required": true, "type": "integer" } ], "responses": { "200": { "description": "Change requests information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "changeRequestDetails" ], "type": "string" }, "data": { "properties": { "rules": { "items": { "$ref": "#/definitions/change-request" }, "type": "array" } }, "required": [ "rules" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 Change requests" ], "description": "Get a change request details", "operationId": "changeRequestDetails", "summary": "Get a change request details", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET https://rudder.example.com/rudder/api/latest/changeRequests --data \"status=open\"\n" } ] }, "post": { "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "parameters": [ { "description": "Change request id", "in": "path", "name": "changeRequestId", "required": true, "type": "integer" }, { "description": "Change request description", "in": "formData", "name": "description", "type": "string" }, { "description": "Change request name", "in": "formData", "name": "name", "type": "string" } ], "responses": { "200": { "description": "Change requests information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "updateChangeRequest" ], "type": "string" }, "data": { "properties": { "rules": { "items": { "$ref": "#/definitions/change-request" }, "type": "array" } }, "required": [ "rules" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 Change requests" ], "description": "Update a change request", "operationId": "updateChangeRequest", "summary": "Update a request details", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST https://rudder.example.com/rudder/api/latest/changeRequests/42 --data \"name=new Name of change request\" -d \"description=add a new description\"" } ] } }, "/changeRequests/{changeRequestId}/accept": { "post": { "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "parameters": [ { "description": "Change request id", "in": "path", "name": "changeRequestId", "required": true, "type": "integer" }, { "description": "New status of the change request", "enum": [ "pending deployment", "deployed" ], "in": "formData", "name": "status", "type": "string" } ], "responses": { "200": { "description": "Change requests information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "acceptChangeRequest" ], "type": "string" }, "data": { "properties": { "rules": { "items": { "$ref": "#/definitions/change-request" }, "type": "array" } }, "required": [ "rules" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 Change requests" ], "description": "Accept a change request", "operationId": "acceptChangeRequest", "summary": "Accept a request details", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET https://rudder.example.com/rudder/api/latest/changeRequests --data \"status=open\"" } ] } }, "/compliance": { "get": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Success", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "getGlobalCompliance" ], "type": "string" }, "data": { "properties": { "globalCompliance": { "properties": { "compliance": { "description": "Global compliance level (`-1` when no policies are defined)", "example": 57, "format": "integer", "type": "number" }, "complianceDetails": { "properties": { "error": { "example": 1.32, "format": "float", "type": "number" }, "noReport": { "example": 36.18, "format": "float", "type": "number" }, "successAlreadyOK": { "example": 48.68, "format": "float", "type": "number" }, "successNotApplicable": { "example": 5.92, "format": "float", "type": "number" }, "successRepaired": { "example": 2.63, "format": "float", "type": "number" }, "unexpectedMissingComponent": { "example": 2.63, "format": "float", "type": "number" }, "unexpectedUnknownComponent": { "example": 2.63, "format": "float", "type": "number" } }, "type": "object" } }, "required": [ "compliance" ], "type": "object" } }, "required": [ "globalCompliance" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "example": "success", "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Compliance" ], "description": "Get current global compliance of a Rudder server", "operationId": "getGlobalCompliance", "summary": "Global compliance", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET 'https://rudder.example.com/rudder/api/latest/compliance?prettify=true'" } ] } }, "/compliance/nodes": { "get": { "produces": [ "application/json" ], "parameters": [ { "default": 10, "description": "Number of depth level of compliance objects to display (1:rules, 2:directives, 3:components, 4:nodes, 5:values, 6:reports)", "in": "query", "name": "level", "type": "integer" } ], "responses": { "200": { "description": "Success", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "getNodesCompliance" ], "type": "string" }, "data": { "properties": { "nodes": { "items": { "properties": { "compliance": { "description": "Rule compliance level", "example": 57.43, "format": "float", "type": "number" }, "complianceDetails": { "properties": { "error": { "example": 1.32, "format": "float", "type": "number" }, "noReport": { "example": 36.18, "format": "float", "type": "number" }, "successAlreadyOK": { "example": 48.68, "format": "float", "type": "number" }, "successNotApplicable": { "example": 5.92, "format": "float", "type": "number" }, "successRepaired": { "example": 2.63, "format": "float", "type": "number" }, "unexpectedMissingComponent": { "example": 2.63, "format": "float", "type": "number" }, "unexpectedUnknownComponent": { "example": 2.63, "format": "float", "type": "number" } }, "type": "object" }, "id": { "description": "id of the node", "example": "f37f4928-fcb5-4acf-a422-d40f123a9670", "format": "uuid", "type": "string" }, "mode": { "enum": [ "full-compliance", "changes-only", "reports-disabled" ], "type": "string" } }, "required": [ "id", "mode", "compliance", "complianceDetails" ], "type": "object" }, "type": "array" } }, "required": [ "nodes" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "example": "success", "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Compliance" ], "description": "Get current compliance of all the nodes of a Rudder server", "operationId": "getNodesCompliance", "summary": "Compliance details for all nodes", "x-code-samples": [ { "lang": "curl", "source": "# To get the compliance information of a specific node\ncurl --header \"X-API-Token: yourToken\" --request GET 'https://rudder.example.com/rudder/api/compliance/nodes?level=2'\n\n# To get the list of nodes wich have a compliance <100 for a given directive (c5881268-5612-48f2-8ef4-0ab8387fccd6) \ncurl -k -H \"X-API-Token: yourToken\" -X GET \"https://rudder.example.com/rudder/api/latest/compliance/nodes?level=3\" \\\n| jq '[.data.nodes[] \n | {\n \"nodeid\":.id, \n \"dirs\": [.rules[].directives[]] \n | map(select(.id == \"c5881268-5612-48f2-8ef4-0ab8387fccd6\" and .compliance < 100)) \n }\n ] \n| map(select(.dirs | length != 0)) \n| [.[] |\n {\"nodeid\":.nodeid, \"comp\":.dirs[0].complianceDetails}\n ]'\n\n" } ] } }, "/compliance/nodes/{nodeId}": { "get": { "produces": [ "application/json" ], "parameters": [ { "default": 10, "description": "Number of depth level of compliance objects to display (1:rules, 2:directives, 3:components, 4:nodes, 5:values, 6:reports)", "in": "query", "name": "level", "type": "integer" }, { "description": "Id of the target node", "format": "uuid (or \"root\")", "in": "path", "name": "nodeId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "getNodeCompliance" ], "type": "string" }, "data": { "properties": { "nodes": { "items": { "properties": { "compliance": { "description": "Rule compliance level", "example": 57.43, "format": "float", "type": "number" }, "complianceDetails": { "properties": { "error": { "example": 1.32, "format": "float", "type": "number" }, "noReport": { "example": 36.18, "format": "float", "type": "number" }, "successAlreadyOK": { "example": 48.68, "format": "float", "type": "number" }, "successNotApplicable": { "example": 5.92, "format": "float", "type": "number" }, "successRepaired": { "example": 2.63, "format": "float", "type": "number" }, "unexpectedMissingComponent": { "example": 2.63, "format": "float", "type": "number" }, "unexpectedUnknownComponent": { "example": 2.63, "format": "float", "type": "number" } }, "type": "object" }, "id": { "description": "id of the node", "example": "f37f4928-fcb5-4acf-a422-d40f123a9670", "format": "uuid", "type": "string" }, "mode": { "enum": [ "full-compliance", "changes-only", "reports-disabled" ], "type": "string" } }, "required": [ "id", "mode", "compliance", "complianceDetails" ], "type": "object" }, "type": "array" } }, "required": [ "nodes" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "example": "success", "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Compliance" ], "description": "Get current compliance of a node of a Rudder server", "operationId": "getNodeCompliance", "summary": "Compliance details by node", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET 'https://rudder.example.com/rudder/api/compliance/nodes/root?level=1'" } ] } }, "/compliance/rules": { "get": { "produces": [ "application/json" ], "parameters": [ { "default": 10, "description": "Number of depth level of compliance objects to display (1:rules, 2:directives, 3:components, 4:nodes, 5:values, 6:reports)", "in": "query", "name": "level", "type": "integer" } ], "responses": { "200": { "description": "Success", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "getRulesCompliance" ], "type": "string" }, "data": { "properties": { "rules": { "items": { "properties": { "compliance": { "description": "Rule compliance level", "example": 57.43, "format": "float", "type": "number" }, "complianceDetails": { "properties": { "error": { "example": 1.32, "format": "float", "type": "number" }, "noReport": { "example": 36.18, "format": "float", "type": "number" }, "successAlreadyOK": { "example": 48.68, "format": "float", "type": "number" }, "successNotApplicable": { "example": 5.92, "format": "float", "type": "number" }, "successRepaired": { "example": 2.63, "format": "float", "type": "number" }, "unexpectedMissingComponent": { "example": 2.63, "format": "float", "type": "number" }, "unexpectedUnknownComponent": { "example": 2.63, "format": "float", "type": "number" } }, "type": "object" }, "id": { "description": "id of the rule", "example": "f37f4928-fcb5-4acf-a422-d40f123a9670", "format": "uuid", "type": "string" }, "mode": { "enum": [ "full-compliance", "changes-only", "reports-disabled" ], "type": "string" } }, "required": [ "id", "mode", "compliance", "complianceDetails" ], "type": "object" }, "type": "array" } }, "required": [ "rules" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "example": "success", "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Compliance" ], "description": "Get current compliance of all the rules of a Rudder server", "operationId": "getRulesCompliance", "summary": "Compliance details for all rules", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET 'https://rudder.example.com/rudder/api/latest/compliance/rules?level=2'" } ] } }, "/compliance/rules/{ruleId}": { "get": { "produces": [ "application/json" ], "parameters": [ { "default": 10, "description": "Number of depth level of compliance objects to display (1:rules, 2:directives, 3:components, 4:nodes, 5:values, 6:reports)", "in": "query", "name": "level", "type": "integer" }, { "description": "Id of the target rule", "format": "uuid", "in": "path", "name": "ruleId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "getRuleCompliance" ], "type": "string" }, "data": { "properties": { "rules": { "items": { "properties": { "compliance": { "description": "Rule compliance level", "example": 57.43, "format": "float", "type": "number" }, "complianceDetails": { "properties": { "error": { "example": 1.32, "format": "float", "type": "number" }, "noReport": { "example": 36.18, "format": "float", "type": "number" }, "successAlreadyOK": { "example": 48.68, "format": "float", "type": "number" }, "successNotApplicable": { "example": 5.92, "format": "float", "type": "number" }, "successRepaired": { "example": 2.63, "format": "float", "type": "number" }, "unexpectedMissingComponent": { "example": 2.63, "format": "float", "type": "number" }, "unexpectedUnknownComponent": { "example": 2.63, "format": "float", "type": "number" } }, "type": "object" }, "id": { "description": "id of the rule", "example": "f37f4928-fcb5-4acf-a422-d40f123a9670", "format": "uuid", "type": "string" }, "mode": { "enum": [ "full-compliance", "changes-only", "reports-disabled" ], "type": "string" } }, "required": [ "id", "mode", "compliance", "complianceDetails" ], "type": "object" }, "type": "array" } }, "required": [ "rules" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "example": "success", "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Compliance" ], "description": "Get current compliance of a rule of a Rudder server", "operationId": "getRuleCompliance", "summary": "Compliance details by rule", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET 'https://rudder.example.com/rudder/api/latest/compliance/rules?level=2'" } ] } }, "/createnodes": { "put": { "produces": [ "application/json" ], "parameters": [ { "content": { "application/json": { "schema": { "$ref": "#/definitions/node-add" } } }, "description": "Description of a node configuration", "in": "query", "name": "Node parameters" } ], "responses": { "200": { "description": "Creation informations", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "createNodes" ], "type": "string" }, "data": { "properties": { "created": { "items": { "description": "created nodes ID", "example": "378740d3-c4a9-4474-8485-478e7e52db52", "type": "string" }, "type": "array" }, "failed": { "items": { "description": "failed nodes ID", "type": "string" }, "type": "array" } }, "required": [ "created", "failed" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 Create Node" ], "description": "Create a new node", "operationId": "createNodes", "summary": "Create a new node", "x-code-samples": [ { "lang": "curl", "source": "nodes.json:\n\n[\n {\n \"id\":\"378740d3-c4a9-4474-8485-478e7e52db52\",\n \"hostname\":\"my.node.hostname.local\",\n \"status\":\"accepted\",\n \"os\":{\n \"type\":\"linux\",\n \"name\":\"debian\",\n \"version\":\"9.5\",\n \"fullName\":\"Debian GNU/Linux 9 (stretch)\"\n },\n \"policyServerId\":\"root\",\n \"machineType\":\"vmware\",\n \"state\":\"enabled\",\n \"policyMode\":\"enforce\",\n \"agentKey\":{\n \"value\":\"----BEGIN CERTIFICATE---- ....\"\n },\n \"properties\":{\n \"tags\":[\n \"some\",\n \"tags\"\n ],\n \"env\":\"prod\",\n \"vars\":{\n \"var1\":\"value1\",\n \"var2\":\"value2\"\n }\n },\n \"ipAddresses\":[\n \"192.168.180.90\",\n \"127.0.0.1\"\n ],\n \"timezone\":{\n \"name\":\"CEST\",\n \"offset\":\"+0200\"\n }\n }\n]\n\ncurl --header \"X-API-Token: yourToken\" --request PUT https://rudder.example.com/rudder/api/latest/createnodes --header \"Content-type: application/json\" --data @nodes.json\n\n" } ] } }, "/cve": { "get": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "CVE check result", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "getAllCve" ], "type": "string" }, "data": { "properties": { "CVEs": { "items": { "$ref": "#/definitions/cveDetails" }, "type": "array" } }, "required": [ "CVEs" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 CVE" ], "description": "Get all CVE details", "operationId": "getAllCve", "summary": "Get all CVE details", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET 'https://rudder.example.com/rudder/api/latest/cve'\n" } ] } }, "/cve/check": { "post": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "CVE check result", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "checkCVE" ], "type": "string" }, "data": { "properties": { "cveChecks": { "items": { "$ref": "#/definitions/cveCheck" }, "type": "array" } }, "required": [ "cveChecks" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 CVE" ], "description": "Trigger a CVE check", "operationId": "checkCVE", "summary": "Trigger a CVE check", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST 'https://rudder.example.com/rudder/api/latest/cve/check'\n" } ] } }, "/cve/check/config": { "get": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "CVE check config", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "getCVECheckConfiguration" ], "type": "string" }, "data": { "properties": { "apiKey": { "description": "Token used by to contact the API to check CVE", "type": "string" }, "url": { "description": "Url used to check CVE", "example": "https://api.rudder.io/cve/v1/", "type": "string" } }, "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 CVE" ], "description": "Get CVE check config", "operationId": "getCVECheckConfiguration", "summary": "Get CVE check config", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET 'https://rudder.example.com/rudder/api/latest/cve/check/config'\n" } ] }, "post": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "in": "body", "name": "body", "schema": { "description": "CVE check config", "properties": { "apiKey": { "description": "Token used by to contact the API to check CVE", "type": "string" }, "url": { "description": "Url used to check CVE", "example": "https://api.rudder.io/cve/v1/", "type": "string" } }, "type": "object" } } ], "responses": { "200": { "description": "new CVE check config", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "updateCVECheckConfiguration" ], "type": "string" }, "data": { "properties": { "apiKey": { "description": "Token used by to contact the API to check CVE", "type": "string" }, "url": { "description": "Url used to check CVE", "example": "https://api.rudder.io/cve/v1/", "type": "string" } }, "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 CVE" ], "description": "Update cve check config", "operationId": "updateCVECheckConfiguration", "summary": "Update cve check config", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET 'https://rudder.example.com/rudder/api/latest/cve/check/config'\n" } ] } }, "/cve/check/last": { "get": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Last CVE check", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "getLastCVECheck" ], "type": "string" }, "data": { "properties": { "CVEChecks": { "items": { "$ref": "#/definitions/cveCheck" }, "type": "array" } }, "required": [ "CVEChecks" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 CVE" ], "description": "Get last CVE check result", "operationId": "getLastCVECheck", "summary": "Get last CVE check result", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET 'https://rudder.example.com/rudder/api/latest/cve/check/last'\n" } ] } }, "/cve/list": { "post": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "in": "body", "name": "body", "schema": { "description": "cveList", "properties": { "cveIds": { "items": { "description": "CVE id", "example": "CVE-2019-5953", "type": "string" }, "type": "array" } }, "type": "object" } } ], "responses": { "200": { "description": "CVE list", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "getCVEList" ], "type": "string" }, "data": { "properties": { "CVEs": { "items": { "$ref": "#/definitions/cveDetails" }, "type": "array" } }, "required": [ "CVEs" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 CVE" ], "description": "Get CVE details, from a list passed a paremeter", "operationId": "getCVEList", "summary": "Get a list of CVE details", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST 'https://rudder.example.com/rudder/api/latest/cve/list'\n" } ] } }, "/cve/update/": { "post": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "in": "body", "name": "body", "schema": { "description": "CVE update config", "properties": { "url": { "description": "Url used to update CVE, will default to one set in config", "example": "https://nvd.nist.gov/feeds/json/cve/1.1", "type": "string" }, "years": { "items": { "description": "Year of the CVE archive to download", "example": "2019", "type": "string" }, "type": "array" } }, "type": "object" } } ], "responses": { "200": { "description": "updated CVE count", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "updateCVE" ], "type": "string" }, "data": { "properties": { "CVEs": { "example": 12345, "type": "integer" } }, "required": [ "CVEs" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 CVE" ], "description": "Update CVE database from remote source", "operationId": "updateCVE", "summary": "Update CVE database from remote source", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST 'https://rudder.example.com/rudder/api/latest/cve/update'\n" } ] } }, "/cve/update/fs": { "post": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "updated CVE count", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "readCVEfromFS" ], "type": "string" }, "data": { "properties": { "CVEs": { "example": 12345, "type": "integer" } }, "required": [ "CVEs" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 CVE" ], "description": "Update CVE database from file system", "operationId": "readCVEfromFS", "summary": "Update CVE database from file system", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST 'https://rudder.example.com/rudder/api/latest/cve/update/FS'\n" } ] } }, "/datasources": { "get": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Data sources information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "getAllDataSources" ], "type": "string" }, "data": { "properties": { "datasources": { "items": { "$ref": "#/definitions/datasource" }, "type": "array" } }, "required": [ "datasources" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 Data sources" ], "description": "Get the configuration of all present data sources", "operationId": "getAllDataSources", "summary": "List all data sources", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET 'https://rudder.example.com/rudder/api/latest/datasources'" } ] }, "put": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "in": "body", "name": "body", "schema": { "$ref": "#/definitions/datasource" } } ], "responses": { "200": { "description": "Created", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "createDataSource" ], "type": "string" }, "data": { "description": "Information about the data sources", "properties": { "datasources": { "items": { "$ref": "#/definitions/datasource" }, "type": "array" } }, "required": [ "datasources" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 Data sources" ], "description": "Create a new data source", "operationId": "createDataSource", "summary": "Create a data source", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request PUT https://rudder.example.com/rudder/api/latest/datasources --header \"Content-type: application/json\" --data @datasources.json" } ] } }, "/datasources/reload": { "post": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Data source reloaded", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "ReloadAllDatasourcesAllNodes" ], "type": "string" }, "data": { "example": "Data for all nodes, for all configured data sources are going to be updated", "type": "string" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 Data sources" ], "description": "Update properties from all data source on all nodes. The call is asynchronous.", "operationId": "ReloadAllDatasourcesAllNodes", "summary": "Update properties from data sources", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST https://rudder.example.com/rudder/api/latest/datasources/reload" } ] } }, "/datasources/reload/{datasourceId}": { "post": { "produces": [ "application/json" ], "parameters": [ { "description": "Id of the data source", "in": "path", "name": "datasourceId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Data source reloaded", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "ReloadOneDatasourceAllNodes" ], "type": "string" }, "data": { "example": "Data for all nodes, for the 'test-data-source' data source are going to be updated", "type": "string" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 Data sources" ], "description": "Update properties from all data source on all nodes. The call is asynchronous.", "operationId": "ReloadOneDatasourceAllNodes", "summary": "Update properties from data sources", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST https://rudder.example.com/rudder/api/latest/datasources/reload/datasourceId" } ] } }, "/datasources/{datasourceId}": { "delete": { "produces": [ "application/json" ], "parameters": [ { "description": "Id of the data source", "in": "path", "name": "datasourceId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Data source information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "deleteDataSource" ], "type": "string" }, "data": { "properties": { "datasources": { "items": { "$ref": "#/definitions/datasource" }, "type": "array" } }, "required": [ "datasources" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 Data sources" ], "description": "Delete a data source configuration", "operationId": "deleteDataSource", "summary": "Delete a data source", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request DELETE https://rudder.example.com/rudder/api/latest/datasources/my-data-source" } ] }, "get": { "produces": [ "application/json" ], "parameters": [ { "description": "Id of the data source", "in": "path", "name": "datasourceId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Data source information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "getDataSource" ], "type": "string" }, "data": { "properties": { "datasources": { "items": { "$ref": "#/definitions/datasource" }, "type": "array" } }, "required": [ "datasources" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 Data sources" ], "description": "Get the configuration of a data source", "operationId": "getDataSource", "summary": "Get data source configuration", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET https://rudder.example.com/rudder/api/latest/datasources/my-data-source" } ] }, "post": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "description": "Id of the data source", "in": "path", "name": "datasourceId", "required": true, "type": "string" }, { "in": "body", "name": "body", "schema": { "$ref": "#/definitions/datasource" } } ], "responses": { "200": { "description": "Data source information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "updateDataSource" ], "type": "string" }, "data": { "properties": { "datasources": { "items": { "$ref": "#/definitions/datasource" }, "type": "array" } }, "required": [ "datasources" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 Data sources" ], "description": "Update the configuration of a data source", "operationId": "updateDataSource", "summary": "Update a data source configuration", "x-code-samples": [ { "lang": "curl", "source": "cat disable-datasource-1.json.json\n{\n \"description\": \"This data source is temporarly no more used and so disabled\",\n \"enabled\": false\n}\n\ncurl --header \"X-API-Token: yourToken\" --request POST https://rudder.example.com/rudder/api/latest/datasources/my-data-source --header \"Content-type: application/json\" --data @disable-datasource-1.json.json" } ] } }, "/directives": { "get": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Directives information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "listDirectives" ], "type": "string" }, "data": { "properties": { "directives": { "items": { "$ref": "#/definitions/directive" }, "type": "array" } }, "required": [ "directives" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Directives" ], "description": "List all directives", "operationId": "listDirectives", "summary": "List all directives", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET https://rudder.example.com/rudder/api/latest/directives" } ] }, "put": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "in": "body", "name": "body", "schema": { "$ref": "#/definitions/directive-new" } } ], "responses": { "200": { "description": "Directives information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "createDirective" ], "type": "string" }, "data": { "properties": { "directives": { "items": { "$ref": "#/definitions/directive" }, "type": "array" } }, "required": [ "directives" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Directives" ], "description": "Create a new directive from provided parameters. You can specify a source directive to clone it.", "operationId": "createDirective", "summary": "Create a directive", "x-code-samples": [ { "lang": "curl", "source": "directives.json:\n\n{\n \"id\": \"cf2a6c72-18ae-4f82-a12c-0b887792db41\",\n \"displayName\": \"Example Directive\",\n \"shortDescription\": \"This in an example Directive to use in Rudder api documentation\",\n \"longDescription\": \"\",\n \"techniqueName\": \"genericVariableDefinition\",\n \"techniqueVersion\": \"2.0\",\n \"tags\": {\n \"env\" : \"production\",\n \"country\" : \"FR\"\n },\n \"parameters\": {\n \"section\": {\n \"name\": \"sections\",\n \"sections\": [\n {\n \"section\": {\n \"name\": \"Variable definition\",\n \"vars\": [\n {\n \"var\": {\n \"name\": \"GENERIC_VARIABLE_CONTENT\",\n \"value\": \"new variable content\"\n }\n },\n {\n \"var\": {\n \"name\": \"GENERIC_VARIABLE_NAME\",\n \"value\": \"new_variable\"\n }\n }\n ]\n }\n }\n ]\n }\n },\n \"priority\": 3,\n \"enabled\": true,\n \"system\": false,\n \"policyMode\": \"default\"\n}\n\ncurl --header \"X-API-Token: yourToken\" --request PUT https://rudder.example.com/rudder/api/latest/directives --header \"Content-type: application/json\" --data @directive.json\n\n" } ] } }, "/directives/{directiveId}": { "delete": { "produces": [ "application/json" ], "parameters": [ { "description": "Id of the directive", "format": "uuid", "in": "path", "name": "directiveId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Directives information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "deleteDirective" ], "type": "string" }, "data": { "properties": { "directives": { "items": { "$ref": "#/definitions/directive" }, "type": "array" } }, "required": [ "directives" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Directives" ], "description": "Delete a directive", "operationId": "deleteDirective", "summary": "Delete a directive", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request DELETE https://rudder.example.com/rudder/api/latest/directives/17dadf50-6056-4c8b-a935-6b97d14b89a7" } ] }, "get": { "produces": [ "application/json" ], "parameters": [ { "description": "Id of the directive", "format": "uuid", "in": "path", "name": "directiveId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Directives information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "directiveDetails" ], "type": "string" }, "data": { "properties": { "directives": { "items": { "$ref": "#/definitions/directive" }, "type": "array" } }, "required": [ "directives" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Directives" ], "description": "Get all information about a given directive", "operationId": "directiveDetails", "summary": "Get directive details", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET https://rudder.example.com/rudder/api/latest/directives/17dadf50-6056-4c8b-a935-6b97d14b89a7" } ] }, "post": { "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "parameters": [ { "description": "Id of the directive", "format": "uuid", "in": "path", "name": "directiveId", "required": true, "type": "string" }, { "description": "Human readable name of the directive", "in": "formData", "name": "displayName", "type": "string" }, { "description": "Is the directive enabled", "in": "formData", "name": "enabled", "type": "boolean" }, { "description": "Directive id", "format": "uuid", "in": "formData", "name": "id", "type": "string" }, { "description": "Description of the technique (rendered as markdown)", "format": "markdown", "in": "formData", "name": "longDescription", "type": "string" }, { "description": "Directive parameters (depends on the source technique)", "in": "formData", "name": "parameters", "type": "object" }, { "description": "Policy mode of the directive", "enum": [ "enforce", "audit" ], "in": "formData", "name": "policyMode", "type": "string" }, { "description": "Directive priority. `0` has highest priority.", "in": "formData", "maximum": 10, "minimum": 0, "name": "priority", "type": "integer" }, { "description": "One line directive description", "in": "formData", "name": "shortDescription", "type": "string" }, { "description": "If true it is an internal Rudder directive", "in": "formData", "name": "system", "type": "boolean" }, { "collectionFormat": "csv", "in": "formData", "items": { "example": { "customer": "MyCompany" }, "properties": { "name": { "description": "Value of the `name` key", "example": "value", "type": "string" } }, "type": "object" }, "name": "tags", "type": "array" }, { "description": "Directive id", "in": "formData", "name": "techniqueName", "type": "string" }, { "description": "Directive id", "in": "formData", "name": "techniqueVersion", "type": "string" } ], "responses": { "200": { "description": "Directives information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "updateDirective" ], "type": "string" }, "data": { "properties": { "directives": { "items": { "$ref": "#/definitions/directive" }, "type": "array" } }, "required": [ "directives" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Directives" ], "description": "Update directive information", "operationId": "updateDirective", "summary": "Update a directive details", "x-code-samples": [ { "lang": "curl", "source": "directive.json:\n{\n \"longDescription\": \"Add a loooooooooooong description\",\n \"parameters\": {\n \"section\": {\n \"name\": \"sections\",\n \"sections\": [\n {\n \"section\": {\n \"name\": \"Variable definition\",\n \"vars\": [\n {\n \"var\": {\n \"name\": \"GENERIC_VARIABLE_CONTENT\",\n \"value\": \"Change Variable Content\"\n }\n },\n {\n \"var\": {\n \"name\": \"GENERIC_VARIABLE_NAME\",\n \"value\": \"new_variable\"\n }\n }\n ]\n }\n }\n ]\n }\n },\n \"priority\": 5\n}\n\ncurl --header \"X-API-Token: yourToken\" --request POST https://rudder.example.com/rudder/api/latest/directives/cf2a6c72-18ae-4f82-a12c-0b887792db41 --header \"Content-type: application/json\" --data @directive.json" } ] } }, "/directives/{directiveId}/check": { "post": { "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "parameters": [ { "description": "Id of the directive", "format": "uuid", "in": "path", "name": "directiveId", "required": true, "type": "string" }, { "description": "Human readable name of the directive", "in": "formData", "name": "displayName", "type": "string" }, { "description": "Is the directive enabled", "in": "formData", "name": "enabled", "type": "boolean" }, { "description": "Directive id", "format": "uuid", "in": "formData", "name": "id", "type": "string" }, { "description": "Description of the technique (rendered as markdown)", "format": "markdown", "in": "formData", "name": "longDescription", "type": "string" }, { "description": "Directive parameters (depends on the source technique)", "in": "formData", "name": "parameters", "type": "object" }, { "description": "Policy mode of the directive", "enum": [ "enforce", "audit" ], "in": "formData", "name": "policyMode", "type": "string" }, { "description": "Directive priority. `0` has highest priority.", "in": "formData", "maximum": 10, "minimum": 0, "name": "priority", "type": "integer" }, { "description": "One line directive description", "in": "formData", "name": "shortDescription", "type": "string" }, { "description": "If true it is an internal Rudder directive", "in": "formData", "name": "system", "type": "boolean" }, { "collectionFormat": "csv", "in": "formData", "items": { "example": { "customer": "MyCompany" }, "properties": { "name": { "description": "Value of the `name` key", "example": "value", "type": "string" } }, "type": "object" }, "name": "tags", "type": "array" }, { "description": "Directive id", "in": "formData", "name": "techniqueName", "type": "string" }, { "description": "Directive id", "in": "formData", "name": "techniqueVersion", "type": "string" } ], "responses": { "200": { "description": "Directives information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "checkDirective" ], "type": "string" }, "data": { "properties": { "directives": { "items": { "$ref": "#/definitions/directive" }, "type": "array" } }, "required": [ "directives" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Directives" ], "description": "Check that update on a directive is valid", "operationId": "checkDirective", "summary": "Check that update on a directive is valid", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST https://rudder.example.com/rudder/api/latest/directives/17dadf50-6056-4c8b-a935-6b97d14b89a7/check --data \"displayName=Name of new directive\"" } ] } }, "/groups": { "get": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Groups information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "listGroups" ], "type": "string" }, "data": { "properties": { "groups": { "items": { "$ref": "#/definitions/group" }, "type": "array" } }, "required": [ "groups" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Groups" ], "description": "List all groups", "operationId": "listGroups", "summary": "List all groups", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET https://rudder.example.com/rudder/api/latest/groups" } ] }, "put": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "in": "body", "name": "body", "schema": { "$ref": "#/definitions/group" } } ], "responses": { "200": { "description": "Group information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "createGroup" ], "type": "string" }, "data": { "properties": { "groups": { "items": { "$ref": "#/definitions/group-new" }, "type": "array" } }, "required": [ "groups" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Groups" ], "description": "Create a new group based in provided parameters", "operationId": "createGroup", "summary": "Create a group", "x-code-samples": [ { "lang": "curl", "source": "groups.json:\n{\n \"category\": \"c355f46e-11b0-4c7a-aedd-6a5f3b0303b6\",\n \"displayName\": \"Example group\",\n \"description\": \"This is an example Group to use in Rudder api documentation\",\n \"query\":\n {\"select\":\"node\",\"composition\":\"Or\",\"where\":\n [\n {\"objectType\":\"node\",\"attribute\":\"nodeId\",\"comparator\":\"eq\",\"value\":\"1ae6ccfe-00ba-44c0-b1aa-362d2f386032\"},\n {\"objectType\":\"node\",\"attribute\":\"nodeId\",\"comparator\":\"eq\",\"value\":\"e4a80fd8-373e-45fc-ad94-2ae618be32e3\"}\n ]\n },\n \"dynamic\": true,\n \"enabled\": true\n}\n\ncurl --header \"X-API-Token: yourToken\" --request PUT https://rudder.example.com/rudder/api/latest/groups --header \"Content-Type: application/json\" --data @group.json\n\n" } ] } }, "/groups/categories": { "put": { "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "parameters": [ { "description": "Group category description", "in": "formData", "name": "description", "type": "string" }, { "default": "{autogenerated}", "description": "Group category id, only provide it when needed.", "format": "uuid", "in": "formData", "name": "id", "type": "string" }, { "description": "Name of the group category", "in": "formData", "name": "name", "required": true, "type": "string" }, { "description": "The parent category of the groups", "format": "uuid", "in": "formData", "name": "parent", "required": true, "type": "string" } ], "responses": { "200": { "description": "Groups category information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "CreateGroupCategory" ], "type": "string" }, "data": { "properties": { "groupCategories": { "items": { "$ref": "#/definitions/group-category" }, "type": "array" } }, "required": [ "groupCategories" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Groups" ], "description": "Create a new group category", "operationId": "CreateGroupCategory", "summary": "Create a group category", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request PUT 'https://rudder.example.com/rudder/api/latest/groups/categories' --data \"name=new category name\" -d \"parent=4306143d-eabf-4478-b7b1-1616f4aa02b5\" -d \"description=A new category created via API'\n" } ] } }, "/groups/categories/{groupCategoryId}": { "delete": { "produces": [ "application/json" ], "parameters": [ { "description": "Group category id", "format": "uuid", "in": "path", "name": "groupCategoryId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Groups category information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "DeleteGroupCategory" ], "type": "string" }, "data": { "properties": { "groupCategories": { "items": { "$ref": "#/definitions/group-category" }, "type": "array" } }, "required": [ "groupCategories" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Groups" ], "description": "Delete a group category. It must have no child groups and no children categories.", "operationId": "DeleteGroupCategory", "summary": "Delete group category", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request DELETE 'https://rudder.example.com/rudder/api/latest/groups/categories/4306143d-eabf-4478-b7b1-1616f4aa02b5'" } ] }, "get": { "produces": [ "application/json" ], "parameters": [ { "description": "Group category id", "format": "uuid", "in": "path", "name": "groupCategoryId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Groups category information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "GetGroupCategoryDetails" ], "type": "string" }, "data": { "properties": { "groupCategories": { "items": { "$ref": "#/definitions/group-category" }, "type": "array" } }, "required": [ "groupCategories" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Groups" ], "description": "Get detailed information about a group category", "operationId": "GetGroupCategoryDetails", "summary": "Get group category details", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET 'https://rudder.example.com/rudder/api/latest/groups/categories/4306143d-eabf-4478-b7b1-1616f4aa02b5'" } ] }, "post": { "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "parameters": [ { "description": "Group category id", "format": "uuid", "in": "path", "name": "groupCategoryId", "required": true, "type": "string" }, { "description": "Group category description", "in": "formData", "name": "description", "type": "string" }, { "description": "Name of the group category", "in": "formData", "name": "name", "required": true, "type": "string" }, { "description": "The parent category of the groups", "format": "uuid", "in": "formData", "name": "parent", "required": true, "type": "string" } ], "responses": { "200": { "description": "Groups category information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "UpdateGroupCategory" ], "type": "string" }, "data": { "properties": { "groupCategories": { "items": { "$ref": "#/definitions/group-category" }, "type": "array" } }, "required": [ "groupCategories" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Groups" ], "description": "Update detailed information about a group category", "operationId": "UpdateGroupCategory", "summary": "Update group category details", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST 'https://rudder.example.com/rudder/api/latest/groups/categories/4306143d-eabf-4478-b7b1-1616f4aa02b5' --data \"name=new category name\"\n" } ] } }, "/groups/tree": { "get": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Groups information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "GetGroupTree" ], "type": "string" }, "data": { "example": { "categories": [ { "categories": [], "description": "That category holds all the system and special target", "groups": [ { "description": "All nodes known by Rudder directly connected to the root server", "displayName": "All nodes managed by root policy server", "dynamic": true, "enabled": true, "id": "hasPolicyServer-root", "nodeIds": [ "dd404bda-2785-4959-abaa-8f37a0bbd85e", "f6223b0e-e2aa-4d1f-b6d1-74de8ea8e513", "root" ], "query": { "composition": "And", "select": "nodeAndPolicyServer", "where": [ { "attribute": "policyServerId", "comparator": "eq", "objectType": "node", "value": "root" } ] } } ], "id": "SystemGroups", "name": "System groups", "parent": "GroupRoot" }, { "categories": [], "description": "", "groups": [ { "description": "", "displayName": "Linux nodes", "dynamic": false, "enabled": true, "id": "79d83ff9-24d8-4be6-b1f7-cbb1c173f7a5", "nodeIds": [], "query": { "composition": "And", "select": "node", "where": [ { "attribute": "OS", "comparator": "eq", "objectType": "node", "value": "Linux" } ] } } ], "id": "38dd2107-a73b-45fb-916d-e110312abb87", "name": "production groups", "parent": "GroupRoot" } ], "description": "This is the root category for the groups (both dynamic and static) and group categories", "groups": [ { "description": "", "displayName": "Test Clients", "dynamic": true, "enabled": true, "id": "af208515-c2f2-4577-bbf4-9fffebbe6629", "nodeIds": [], "query": { "composition": "Or", "select": "node", "where": [ { "attribute": "nodeHostname", "comparator": "regex", "objectType": "node", "value": "servername.*company.net" }, { "attribute": "nodeHostname", "comparator": "regex", "objectType": "node", "value": "lt serverbla.*company.net" } ] } }, { "description": "", "displayName": "Test Clients", "dynamic": true, "enabled": true, "id": "d7634b2d-7189-422b-9971-24c29b75da46", "nodeIds": [], "query": { "composition": "Or", "select": "node", "where": [ { "attribute": "nodeHostname", "comparator": "regex", "objectType": "node", "value": "servername.*company.net" }, { "attribute": "nodeHostname", "comparator": "regex", "objectType": "node", "value": "lt serverbla.*company.net" } ] } } ], "id": "GroupRoot", "name": "Root of the group and group categories", "parent": "GroupRoot" }, "properties": { "groupCategories": { "description": "Group tree", "example": null, "type": "object" } }, "required": [ "groupCategories" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Groups" ], "description": "Get all available groups and their categories in a tree", "operationId": "GetGroupTree", "summary": "Get groups tree", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET https://rudder.example.com/rudder/api/latest/groups/tree\n" } ] } }, "/groups/{groupId}": { "delete": { "produces": [ "application/json" ], "parameters": [ { "description": "Id of the group", "format": "uuid", "in": "path", "name": "groupId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Groups information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "deleteGroup" ], "type": "string" }, "data": { "properties": { "groups": { "items": { "$ref": "#/definitions/group" }, "type": "array" } }, "required": [ "groups" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Groups" ], "description": "Update detailed information about a group", "operationId": "deleteGroup", "summary": "Delete a group", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request DELETE 'https://rudder.example.com/rudder/api/latest/groups/17dadf50-6056-4c8b-a935-6b97d14b89a7'" } ] }, "get": { "produces": [ "application/json" ], "parameters": [ { "description": "Id of the group", "format": "uuid", "in": "path", "name": "groupId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Groups information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "groupDetails" ], "type": "string" }, "data": { "properties": { "groups": { "items": { "$ref": "#/definitions/group" }, "type": "array" } }, "required": [ "groups" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Groups" ], "description": "Get detailed information about a group", "operationId": "groupDetails", "summary": "Get group details", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET 'https://rudder.example.com/rudder/api/latest/groups/17dadf50-6056-4c8b-a935-6b97d14b89a7'" } ] }, "post": { "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "parameters": [ { "description": "Id of the group", "format": "uuid", "in": "path", "name": "groupId", "required": true, "type": "string" }, { "description": "Id of the new group's category", "format": "uuid", "in": "formData", "name": "category", "type": "string" }, { "description": "Group description", "in": "formData", "name": "description", "type": "string" }, { "description": "Name of the group", "in": "formData", "name": "displayName", "type": "string" }, { "default": true, "description": "Should the group be dynamically refreshed (if not, it is a static group)", "in": "formData", "name": "dynamic", "type": "boolean" }, { "default": true, "description": "Enable or disable the group", "in": "formData", "name": "enabled", "type": "boolean" }, { "description": "The criteria defining the group. If not provided, the group will be empty.", "in": "formData", "name": "query", "type": "object" } ], "responses": { "200": { "description": "Groups information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "updateGroup" ], "type": "string" }, "data": { "properties": { "groups": { "items": { "$ref": "#/definitions/group" }, "type": "array" } }, "required": [ "groups" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Groups" ], "description": "Update detailed information about a group", "operationId": "updateGroup", "summary": "Update group details", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST 'https://rudder.example.com/rudder/api/latest/groups/17dadf50-6056-4c8b-a935-6b97d14b89a7' --data \"displayName=New name of group\"" } ] } }, "/groups/{groupId}/reload": { "post": { "produces": [ "application/json" ], "parameters": [ { "description": "Id of the group", "format": "uuid", "in": "path", "name": "groupId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Groups information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "reloadGroup" ], "type": "string" }, "data": { "properties": { "groups": { "items": { "$ref": "#/definitions/group" }, "type": "array" } }, "required": [ "groups" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Groups" ], "description": "Recompute the content of a group", "operationId": "reloadGroup", "summary": "Reload a group", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST 'https://rudder.example.com/rudder/api/latest/groups/17dadf50-6056-4c8b-a935-6b97d14b89a7/reload'" } ] } }, "/inventories/info": { "get": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Inventories information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "queueInformation" ], "type": "string" }, "data": { "description": "Information about the service", "properties": { "queueMaxSize": { "example": 50, "type": "integer" }, "queueSaturated": { "description": "Is the inventory queue full", "example": false, "type": "boolean" } }, "required": [ "queueMaxSize", "queueSaturated" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Inventories" ], "description": "Provide information about the current state of the inventory processor", "operationId": "queueInformation", "summary": "Get information about inventory processing queue", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" https://rudder.example.com/rudder/api/latest/" } ] } }, "/inventories/upload": { "post": { "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "parameters": [ { "format": "binary", "in": "formData", "name": "file", "type": "string" }, { "format": "binary", "in": "formData", "name": "signature", "type": "string" } ], "responses": { "200": { "description": "Inventory uploaded", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "uploadInventory" ], "type": "string" }, "data": { "example": "Inventory 'file.xml' for Node 'c1bab9fc-bcf6-4d59-a397-84c8e2fc06c0' added to processing queue.", "type": "string" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Inventories" ], "description": "Upload an inventory to the web application", "operationId": "uploadInventory", "summary": "Upload an inventory for processing", "x-code-samples": [ { "lang": "curl", "source": "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\"" } ] } }, "/inventories/watcher/restart": { "post": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Started", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "fileWatcherRestart" ], "type": "string" }, "data": { "example": "Incoming inventory watcher restarted", "type": "string" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Inventories" ], "description": "Restart the inventory watcher if necessary", "operationId": "fileWatcherRestart", "summary": "Restart inventory watcher", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST 'https://rudder.example.com/rudder/api/latest/inventories/watcher/restart'" } ] } }, "/inventories/watcher/start": { "post": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Started", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "fileWatcherStart" ], "type": "string" }, "data": { "example": "Incoming inventory watcher started", "type": "string" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Inventories" ], "description": "Start the inventory watcher if necessary", "operationId": "fileWatcherStart", "summary": "Start inventory watcher", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST 'https://rudder.example.com/rudder/api/latest/inventories/watcher/start'" } ] } }, "/inventories/watcher/stop": { "post": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Stopped", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "fileWatcherStop" ], "type": "string" }, "data": { "example": "Incoming inventory watcher stopped", "type": "string" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Inventories" ], "description": "Stop the inventory watcher if necessary", "operationId": "fileWatcherStop", "summary": "Stop inventory watcher", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST 'https://rudder.example.com/rudder/api/latest/inventories/watcher/stop'" } ] } }, "/nodes": { "get": { "produces": [ "application/json" ], "parameters": [ { "default": "default", "description": "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.\n* **minimal** includes: `id`, `hostname` and `status`\n* **default** includes **minimal** plus `architectureDescription`, `description`, `ipAddresses`, `lastRunDate`, `lastInventoryDate`, `machine`, `os`, `managementTechnology`, `policyServerId`, `properties`, `policyMode `, `ram` and `timezone`\n* **full** includes: **default** plus `accounts`, `bios`, `controllers`, `environmentVariables`, `fileSystems`, `managementTechnologyDetails`, `memories`, `networkInterfaces`, `ports`, `processes`, `processors`, `slots`, `software`, `sound`, `storage`, `videos` and `virtualMachines`", "format": "comma-separated list", "in": "query", "name": "include", "type": "string" }, { "content": { "application/json": { "schema": { "properties": { "composition": { "default": "and", "description": "Boolean operator to use between each `where` criteria.", "enum": [ "and", "or" ], "example": "and", "type": "string" }, "select": { "default": "node", "description": "What kind of data we want to include. Here we can get policy servers/relay by setting `nodeAndPolicyServer`. Only used if `where` is defined.", "type": "string" }, "where": { "description": "List of criteria", "items": { "properties": { "attribute": { "description": "Attribute to compare", "example": "OS", "type": "string" }, "comparator": { "description": "Comparator to use", "example": "eq", "type": "string" }, "objectType": { "description": "Type of the object", "example": "node", "type": "string" }, "value": { "description": "Value to compare against", "example": "Linux", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "The criterion you want to find for your nodes. Replaces the `where`, `composition` and `select` parameters in a single parameter.", "in": "query", "name": "query" }, { "content": { "application/json": { "schema": { "description": "List of criteria", "items": { "properties": { "attribute": { "description": "Attribute to compare", "example": "OS", "type": "string" }, "comparator": { "description": "Comparator to use", "example": "eq", "type": "string" }, "objectType": { "description": "Type of the object", "example": "node", "type": "string" }, "value": { "description": "Value to compare against", "example": "Linux", "type": "string" } }, "type": "object" }, "type": "array" } } }, "description": "The criterion you want to find for your nodes", "in": "query", "name": "where" }, { "default": "and", "description": "Boolean operator to use between each `where` criteria.", "enum": [ "and", "or" ], "in": "query", "name": "composition", "type": "string" }, { "default": "node", "description": "What kind of data we want to include. Here we can get policy servers/relay by setting `nodeAndPolicyServer`. Only used if `where` is defined.", "in": "query", "name": "select", "type": "string" } ], "responses": { "200": { "description": "Nodes", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "listAcceptedNodes" ], "type": "string" }, "data": { "description": "Information about the nodes", "properties": { "nodes": { "items": { "$ref": "#/definitions/node-full" }, "type": "array" } }, "required": [ "nodes" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Nodes" ], "description": "Get information about the nodes managed by the target server", "operationId": "listAcceptedNodes", "summary": "List managed nodes", "x-code-samples": [ { "lang": "curl", "source": "# To get the Linux nodes with a hostname starting with \"node1\"\ncurl --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.*\"\\}\\]'\n\n# To get the list of nodes with their agent version\ncurl -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}'\n\n# To get information about the eth0 interface of a specific node\ncurl -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\")'\n# It gives:\n#\n#{\n# \"name\": \"eth0\",\n# \"type\": \"ethernet\",\n# \"status\": \"Up\",\n# \"macAddress\": \"52:54:00:49:45:ac\",\n# \"ipAddresses\": [\n# \"fe80:0:0:0:5054:ff:fe49:45ac\",\n# \"192.168.110.21\"\n# ]\n#}\n\n\n" }, { "lang": "python", "source": "import json\nimport requests\n\n# Get all nodes having a hostname starting with node1 and based on Linux and only display minimal information (id, hostname, status)\nurl = \"https://rudder.example.com/rudder/api/latest/nodes\"\nlinux = {\"objectType\": \"node\", \"attribute\": \"OS\",\n \"comparator\": \"eq\", \"value\": \"Linux\"}\nnode1 = {\"objectType\": \"node\", \"attribute\": \"nodeHostname\",\n \"comparator\": \"regex\", \"value\": \"node1.*\"}\nwhere = [linux, node1]\nparams = {\"where\": json.dumps(where), \"include\": \"minimal\"}\nheaders = {\"X-API-TOKEN\": \"yourToken\"}\nrequests.get(url, params=params, headers=headers, verify=False)\n" } ] } }, "/nodes/applyPolicy": { "post": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Result", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "applyPolicyAllNodes" ], "type": "string" }, "data": { "items": { "properties": { "hostname": { "description": "Node hostname", "example": "node.example.com", "type": "string" }, "id": { "description": "Rudder id of the node", "example": "249e14ac-2418-457c-a27d-1650907b13c7", "format": "uuid (or \"root\")", "type": "string" }, "result": { "description": "Result or policy application trigger", "example": "Started", "type": "string" } }, "type": "object" }, "type": "array" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Nodes" ], "description": "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.", "operationId": "applyPolicyAllNodes", "summary": "Trigger an agent run on all nodes", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST --header \"Content-Type: application/json\" https://rudder.example.com/rudder/api/latest/nodes/applyPolicy" } ] } }, "/nodes/pending/{nodeId}": { "post": { "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "parameters": [ { "description": "Id of the target node", "format": "uuid (or \"root\")", "in": "path", "name": "nodeId", "required": true, "type": "string" }, { "description": "New status of the pending node", "enum": [ "accepted", "refused" ], "in": "formData", "name": "status", "type": "string" } ], "responses": { "200": { "description": "Nodes", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "changePendingNodeStatus" ], "type": "string" }, "data": { "description": "Information about the node", "properties": { "nodes": { "items": { "$ref": "#/definitions/node-full" }, "type": "array" } }, "required": [ "nodes" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Nodes" ], "description": "Accept or refuse a pending node", "operationId": "changePendingNodeStatus", "summary": "Update pending Node status", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST https://rudder.example.com/rudder/api/latest/nodes/pending/17dadf50-6056-4c8b-a935-6b97d14b89a7 --data \"status=accepted\"" } ] } }, "/nodes/{nodeId}": { "delete": { "produces": [ "application/json" ], "parameters": [ { "description": "Id of the target node", "format": "uuid (or \"root\")", "in": "path", "name": "nodeId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Nodes", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "deleteNode" ], "type": "string" }, "data": { "description": "Information about the node", "properties": { "nodes": { "items": { "$ref": "#/definitions/node-full" }, "type": "array" } }, "required": [ "nodes" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Nodes" ], "description": "Remove a node from the Rudder server. It won't be managed anymore.", "operationId": "deleteNode", "summary": "Delete a node", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request DELETE https://rudder.example.com/rudder/api/latest/nodes/17dadf50-6056-4c8b-a935-6b97d14b89a7\n" } ] }, "get": { "produces": [ "application/json" ], "parameters": [ { "description": "Id of the target node", "format": "uuid (or \"root\")", "in": "path", "name": "nodeId", "required": true, "type": "string" }, { "default": "default", "description": "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.\n* **minimal** includes: `id`, `hostname` and `status`\n* **default** includes **minimal** plus `architectureDescription`, `description`, `ipAddresses`, `lastRunDate`, `lastInventoryDate`, `machine`, `os`, `managementTechnology`, `policyServerId`, `properties`, `policyMode `, `ram` and `timezone`\n* **full** includes: **default** plus `accounts`, `bios`, `controllers`, `environmentVariables`, `fileSystems`, `managementTechnologyDetails`, `memories`, `networkInterfaces`, `ports`, `processes`, `processors`, `slots`, `software`, `sound`, `storage`, `videos` and `virtualMachines`", "format": "comma-separated list", "in": "query", "name": "include", "type": "string" } ], "responses": { "200": { "description": "Nodes", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "nodeDetails" ], "type": "string" }, "data": { "description": "Information about the node", "properties": { "nodes": { "items": { "$ref": "#/definitions/node-full" }, "type": "array" } }, "required": [ "nodes" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Nodes" ], "description": "Get details about a given node", "operationId": "nodeDetails", "summary": "Get information about a node", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" https://rudder.example.com/rudder/api/latest/nodes/17dadf50-6056-4c8b-a935-6b97d14b89a7\\?include=full" } ] }, "post": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "description": "Id of the target node", "format": "uuid (or \"root\")", "in": "path", "name": "nodeId", "required": true, "type": "string" }, { "in": "body", "name": "body", "schema": { "$ref": "#/definitions/node-settings" } } ], "responses": { "200": { "description": "Nodes", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "updateNode" ], "type": "string" }, "data": { "description": "Information about the node", "properties": { "nodes": { "items": { "$ref": "#/definitions/node-full" }, "type": "array" } }, "required": [ "nodes" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Nodes" ], "description": "Update node settings and properties", "operationId": "updateNode", "summary": "Update node settings and properties", "x-code-samples": [ { "lang": "curl", "source": "# Given the \"data.json\" JSON file with content:\n{ \"properties\": [\n { \"name\": \"env_type\" , \"value\": \"production\" },\n { \"name\": \"shell\" , \"value\": \"/bin/sh\" },\n { \"name\": \"utf-8 poetry\", \"value\": \"ᚠᛇᚻ᛫ᛒᛦᚦ᛫ᚠᚱᚩᚠᚢᚱ᛫ᚠᛁᚱᚪ᛫ᚷᛖᚻᚹᛦᛚᚳᚢᛗ\" }\n]\n, \"policyMode\" : \"audit\"\n}\n# Setting properties from \"data.json\" and policy mode to audit:\ncurl --header \"X-API-Token: yourToken\" --request POST --header \"Content-Type: application/json\" https://rudder.example.com/rudder/api/latest/nodes/17dadf50-6056-4c8b-a935-6b97d14b89a7 --data @properties.json\n\n# Removing the key \"utf-8 poetry\" from the command line and updating the \"env_type\" one\ncurl --header \"X-API-Token: yourToken\" --request POST --header \"Content-Type: application/json\" https://rudder.example.com/rudder/api/latest/nodes/17dadf50-6056-4c8b-a935-6b97d14b89a7 --data '{ \"properties\": [{ \"name\":\"utf-8 poetry\", \"value\":\"\"}, {\"name\":\"env_type\", \"value\":\"deprovisioned\"}] }'\n\n# Removing the key \"env_type\" and changing \"shell\" and use default policy mode\ncurl --header \"X-API-Token: yourToken\" --request POST https://rudder.example.com/rudder/api/latest/nodes/17dadf50-6056-4c8b-a935-6b97d14b89a7 --data \"properties=shell=/bin/false\" -d \"properties=env_type=\" -d \"policyMode=default\"\n" } ] } }, "/nodes/{nodeId}/applyPolicy": { "post": { "produces": [ "text/plain" ], "parameters": [ { "description": "Id of the target node", "format": "uuid (or \"root\")", "in": "path", "name": "nodeId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Agent output", "schema": { "example": "Start execution with config [20200218-112602-11ce4f64]\nHostname M| State Technique Component Key Message 192.168.210.5 E| compliant Common ncf Initialization Configuration library initialization was correct 192.168.210.5 E| compliant Common Update Policy and configuration library are already up to date. No action required. [...]\n## Summary ##################################################################### 90 components verified in 15 directives\n => 62 components in Enforce mode\n -> 48 compliant\n -> 13 not-applicable\n -> 1 error\n => 28 components in Audit mode\n -> 15 compliant\n -> 3 not-applicable\n -> 10 non-compliant\nExecution time: 8.89s ################################################################################", "type": "string" } } }, "tags": [ "Nodes" ], "description": "This API allows to trigger an agent run on the target node. Response is a stream of the actual agent run on the node.", "operationId": "applyNode", "summary": "Trigger an agent run", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" https://rudder.example.com/rudder/api/latest/nodes/17dadf50-6056-4c8b-a935-6b97d14b89a7\\?include=full" } ] } }, "/nodes/{nodeId}/fetchData": { "post": { "produces": [ "application/json" ], "parameters": [ { "description": "Id of the target node", "format": "uuid (or \"root\")", "in": "path", "name": "nodeId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Data sources reloaded", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "ReloadAllDatasourcesOneNode" ], "type": "string" }, "data": { "example": "Data for node '4e3336f9-ace8-44d6-8d07-496ff1631b01', for all configured data sources, is going to be updated", "type": "string" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 Data sources" ], "description": "Update properties from all data sources on one nodes. The call is asynchronous.", "operationId": "ReloadAllDatasourcesOneNode", "summary": "Update properties for one node from all data sources", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST https://rudder.example.com/rudder/api/latest/nodes/17dadf50-6056-4c8b-a935-6b97d14b89a7/fetchData" } ] } }, "/nodes/{nodeId}/fetchData/{datasourceId}": { "post": { "produces": [ "application/json" ], "parameters": [ { "description": "Id of the target node", "format": "uuid (or \"root\")", "in": "path", "name": "nodeId", "required": true, "type": "string" }, { "description": "Id of the data source", "in": "path", "name": "datasourceId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Data sources reloaded", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "ReloadOneDatasourceOneNode" ], "type": "string" }, "data": { "example": "Data for node '4e3336f9-ace8-44d6-8d07-496ff1631b01', for ' test-data-source' data source, is going to be updated", "type": "string" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 Data sources" ], "description": "Update properties from a data source on one nodes. The call is asynchronous.", "operationId": "ReloadOneDatasourceOneNode", "summary": "Update properties for one node from a data source", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST https://rudder.example.com/rudder/api/latest/nodes/nodeId/fetchData/datasourceId" } ] } }, "/parameters": { "get": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Settings", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "listParameters" ], "type": "string" }, "data": { "description": "Parameters", "properties": { "parameters": { "items": { "$ref": "#/definitions/parameter" }, "type": "array" } }, "required": [ "parameters" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Parameters" ], "description": "Get the current value of all the global parameters", "operationId": "listParameters", "summary": "List all global parameters", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" https://rudder.example.com/rudder/api/latest/parameters" } ] }, "put": { "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "parameters": [ { "description": "Description of the parameter", "in": "formData", "name": "description", "type": "string" }, { "description": "Name of the parameter", "in": "formData", "name": "id", "required": true, "type": "string" }, { "description": "Is the global parameter overridable by node", "in": "formData", "name": "overridable", "type": "boolean" }, { "description": "Value of the parameter", "format": "string or JSON", "in": "formData", "name": "value" } ], "responses": { "200": { "description": "Settings", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "createParameter" ], "type": "string" }, "data": { "description": "Parameters", "properties": { "parameters": { "items": { "$ref": "#/definitions/parameter" }, "type": "array" } }, "required": [ "parameters" ], "type": "object" }, "id": { "description": "Id of the parameter", "example": "rudder_file_edit_footer", "type": "string" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data", "id" ], "type": "object" } } }, "tags": [ "Parameters" ], "description": "Create a new global parameter", "operationId": "createParameter", "summary": "Create a new parameter", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --header \"Content-Type: application/json\" --request PUT https://rudder.example.com/rudder/api/latest/parameters --data @JSON-file-name" } ] } }, "/parameters/{parameterId}": { "delete": { "produces": [ "application/json" ], "parameters": [ { "description": "Id of the parameter to manage", "in": "path", "name": "parameterId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Settings", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "deleteParameter" ], "type": "string" }, "data": { "description": "Parameters", "properties": { "parameters": { "items": { "$ref": "#/definitions/parameter" }, "type": "array" } }, "required": [ "parameters" ], "type": "object" }, "id": { "description": "Id of the parameter", "example": "rudder_file_edit_footer", "type": "string" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data", "id" ], "type": "object" } }, "500": { "description": "Non existing parameter", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "deleteParameter" ], "type": "string" }, "errorDetails": { "example": "Could not delete Parameter rudder_file_edit_footer cause is: Could not find Parameter rudder_file_edit_footer.", "type": "string" }, "id": { "description": "Id of the parameter", "example": "rudder_file_edit_footer", "type": "string" }, "result": { "description": "Result of the request", "enum": [ "error" ], "type": "string" } }, "required": [ "result", "action", "data", "id" ], "type": "object" } } }, "tags": [ "Parameters" ], "description": "Delete an existing parameter", "operationId": "deleteParameter", "summary": "Delete a parameter", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request DELETE https://rudder.example.com/rudder/api/latest/parameters/ParameterId" } ] }, "get": { "produces": [ "application/json" ], "parameters": [ { "description": "Id of the parameter to manage", "in": "path", "name": "parameterId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Settings", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "parameterDetails" ], "type": "string" }, "data": { "description": "Parameters", "properties": { "parameters": { "items": { "$ref": "#/definitions/parameter" }, "type": "array" } }, "required": [ "parameters" ], "type": "object" }, "id": { "description": "Id of the parameter", "example": "rudder_file_edit_footer", "type": "string" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data", "id" ], "type": "object" } } }, "tags": [ "Parameters" ], "description": "Get the current value of a given parameter", "operationId": "parameterDetails", "summary": "Get the value of a parameter", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" https://rudder.example.com/rudder/api/latest/parameters/ParameterId" } ] }, "post": { "produces": [ "application/json" ], "parameters": [ { "description": "Id of the parameter to manage", "in": "path", "name": "parameterId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Settings", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "updateParameter" ], "type": "string" }, "data": { "description": "Parameters", "properties": { "parameters": { "items": { "$ref": "#/definitions/parameter" }, "type": "array" } }, "required": [ "parameters" ], "type": "object" }, "id": { "description": "Id of the parameter", "example": "rudder_file_edit_footer", "type": "string" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data", "id" ], "type": "object" } } }, "tags": [ "Parameters" ], "description": "Update the properties of a parameter", "operationId": "updateParameter", "summary": "Update a parameter's value", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST https://rudder.example.com/rudder/api/latest/parameters/ParameterId --data \"value=### Edited by Rudder ###\"" } ] } }, "/regenerate/policies": { "post": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Success", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "regeneratePolicies" ], "type": "string" }, "data": { "properties": { "policies": { "enum": [ "Started" ], "type": "string" } }, "required": [ "policies" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "System" ], "description": "Trigger a full policy generation", "operationId": "regeneratePolicies", "summary": "Trigger a new policy generation", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST 'https://rudder.example.com/rudder/api/latest/system/regenerate/policies'" } ] } }, "/reload/groups": { "post": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Service reload", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "reloadGroups" ], "type": "string" }, "data": { "properties": { "groups": { "enum": [ "Started" ], "type": "string" } }, "required": [ "groups" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "System" ], "description": "Reload dynamic groups", "operationId": "reloadGroups", "summary": "Reload dynamic groups", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST 'https://rudder.example.com/rudder/api/latest/system/reload/groups'\n" } ] } }, "/reload/techniques": { "post": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Service reload", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "reloadTechniques" ], "type": "string" }, "data": { "properties": { "techniques": { "enum": [ "Started" ], "type": "string" } }, "required": [ "techniques" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "System" ], "description": "Reload techniques from local technique library", "operationId": "reloadTechniques", "summary": "Reload techniques", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST 'https://rudder.example.com/rudder/api/latest/system/reload/techniques'\n" } ] } }, "/rules": { "get": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Rules information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "listRules" ], "type": "string" }, "data": { "properties": { "rules": { "items": { "$ref": "#/definitions/rule" }, "type": "array" } }, "required": [ "rules" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Rules" ], "description": "List all rules", "operationId": "listRules", "summary": "List all rules", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET 'https://rudder.example.com/rudder/api/latest/rules'\n\n# To get information about the target (included/excluded) groups of the rules\ncurl -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}'\n" } ] }, "put": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "in": "body", "name": "body", "schema": { "$ref": "#/definitions/rule-new" } } ], "responses": { "200": { "description": "Rules information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "createRule" ], "type": "string" }, "data": { "properties": { "rules": { "items": { "$ref": "#/definitions/rule" }, "type": "array" } }, "required": [ "rules" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Rules" ], "description": "Create a new rule. You can specify a source rule to clone it.", "operationId": "createRule", "summary": "Create a rule", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request PUT 'https://rudder.example.com/rudder/api/latest/rules' --data \"displayName=Name of New Rule\"" } ] } }, "/rules/categories": { "put": { "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "parameters": [ { "description": "Rules category description", "in": "formData", "name": "description", "type": "string" }, { "default": "{autogenerated}", "description": "Rule category id, only provide it when needed.", "format": "uuid", "in": "formData", "name": "id", "type": "string" }, { "description": "Name of the rule category", "in": "formData", "name": "name", "required": true, "type": "string" }, { "description": "The parent category of the rules", "format": "uuid", "in": "formData", "name": "parent", "required": true, "type": "string" } ], "responses": { "200": { "description": "Rules category information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "CreateRuleCategory" ], "type": "string" }, "data": { "properties": { "ruleCategories": { "items": { "$ref": "#/definitions/rule-category" }, "type": "array" } }, "required": [ "ruleCategories" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Rules" ], "description": "Create a new rule category", "operationId": "CreateRuleCategory", "summary": "Create a rule category", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request PUT 'https://rudder.example.com/rudder/api/latest/rules/categories' --data \"name=new category\" -d \"parent=4306143d-eabf-4478-b7b1-1616f4aa02b5\" -d \"description=A new category created via API\"\n" } ] } }, "/rules/categories/{ruleCategoryId}": { "delete": { "produces": [ "application/json" ], "parameters": [ { "description": "Rule category id", "format": "uuid", "in": "path", "name": "ruleCategoryId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Groups category information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "DeleteRuleCategory" ], "type": "string" }, "data": { "properties": { "groupCategories": { "items": { "$ref": "#/definitions/rule-category" }, "type": "array" } }, "required": [ "groupCategories" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Rules" ], "description": "Delete a group category. It must have no child groups and no children categories.", "operationId": "DeleteRuleCategory", "summary": "Delete group category", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request DELETE 'https://rudder.example.com/rudder/api/latest/rules/categories/4306143d-eabf-4478-b7b1-1616f4aa02b5?prettify=true'" } ] }, "get": { "produces": [ "application/json" ], "parameters": [ { "description": "Rule category id", "format": "uuid", "in": "path", "name": "ruleCategoryId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Rules category information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "GetRuleCategoryDetails" ], "type": "string" }, "data": { "properties": { "rulesCategories": { "items": { "$ref": "#/definitions/rule-category" }, "type": "array" } }, "required": [ "rulesCategories" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Rules" ], "description": "Get detailed information about a rule category", "operationId": "GetRuleCategoryDetails", "summary": "Get rule category details", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET 'https://rudder.example.com/rudder/api/latest/rules/categories/4306143d-eabf-4478-b7b1-1616f4aa02b5?prettify=true'" } ] }, "post": { "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "parameters": [ { "description": "Rule category id", "format": "uuid", "in": "path", "name": "ruleCategoryId", "required": true, "type": "string" }, { "description": "Rules category description", "in": "formData", "name": "description", "type": "string" }, { "description": "Name of the rule category", "in": "formData", "name": "name", "required": true, "type": "string" }, { "description": "The parent category of the rules", "format": "uuid", "in": "formData", "name": "parent", "required": true, "type": "string" } ], "responses": { "200": { "description": "Rules category information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "UpdateRuleCategory" ], "type": "string" }, "data": { "properties": { "ruleCategories": { "items": { "$ref": "#/definitions/rule-category" }, "type": "array" } }, "required": [ "ruleCategories" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Rules" ], "description": "Update detailed information about a rule category", "operationId": "UpdateRuleCategory", "summary": "Update rule category details", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST 'https://rudder.example.com/rudder/api/latest/rules/categories/4306143d-eabf-4478-b7b1-1616f4aa02b5?prettify=true' --data \"name=new category name\"" } ] } }, "/rules/tree": { "get": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Rules information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "GetRuleTree" ], "type": "string" }, "data": { "example": { "categories": [ { "categories": [ { "categories": [], "description": "", "id": "f45ec2fd-69f4-4669-9c22-1af3abe2a107", "name": "Specific dev category", "parent": "4306143d-eabf-4478-b7b1-1616f4aa02b5", "rules": [ { "directives": [], "displayName": "my specific Rule", "enabled": true, "id": "b7fda4e7-3616-4e99-89b0-8ffadaf6b0f0", "longDescription": "", "shortDescription": "", "system": false, "targets": [] } ] } ], "description": "", "id": "4306143d-eabf-4478-b7b1-1616f4aa02b5", "name": "Dev category", "parent": "rootRuleCategory", "rules": [ { "directives": [], "displayName": "dev Rule", "enabled": true, "id": "f2aa50a9-961c-4cce-a266-380cffcdce32", "longDescription": "", "shortDescription": "", "system": false, "targets": [] } ] } ], "description": "This is the main category of Rules", "id": "rootRuleCategory", "name": "Rules", "parent": "rootRuleCategory", "rules": [ { "directives": [], "displayName": "Global security policy", "enabled": true, "id": "43cde273-5bb0-466f-8850-7d3fdde03253", "longDescription": "", "shortDescription": "", "system": false, "targets": [] }, { "directives": [ "bff45fe2-8233-4d28-96aa-78b0390b548b" ], "displayName": "Global configuration for all nodes", "enabled": false, "id": "32377fd7-02fd-43d0-aab7-28460a91347b", "longDescription": "This Rule was created automatically when Rudder was installed. It can be used to target Directives to all nodes (including the Rudder root server itself), or deleted if you would rather create your own set of Rules (it will never be created again).", "shortDescription": "", "system": false, "targets": [ { "exclude": { "or": [] }, "include": { "or": [ "special:all", "special:all_exceptPolicyServers", "special:all_nodes_without_role" ] } } ] } ] }, "properties": { "ruleCategories": { "description": "Rule tree", "example": null, "type": "object" } }, "required": [ "ruleCategories" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Rules" ], "description": "Get all available rules and their categories in a tree", "operationId": "GetRuleTree", "summary": "Get rules tree", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET 'https://rudder.example.com/rudder/api/latest/rules/tree?prettify=true'" } ] } }, "/rules/{ruleId}": { "delete": { "produces": [ "application/json" ], "parameters": [ { "description": "Id of the target rule", "format": "uuid", "in": "path", "name": "ruleId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Rules information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "deleteRule" ], "type": "string" }, "data": { "properties": { "rules": { "items": { "$ref": "#/definitions/rule" }, "type": "array" } }, "required": [ "rules" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Rules" ], "description": "Delete a rule.", "operationId": "deleteRule", "summary": "Delete a rule", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request DELETE 'https://rudder.example.com/rudder/api/latest/rules/176ad06b-ed02-4da3-8053-16225d217741'" } ] }, "get": { "produces": [ "application/json" ], "parameters": [ { "description": "Id of the target rule", "format": "uuid", "in": "path", "name": "ruleId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Rules information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "ruleDetails" ], "type": "string" }, "data": { "properties": { "rules": { "items": { "$ref": "#/definitions/rule" }, "type": "array" } }, "required": [ "rules" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Rules" ], "description": "Get the details of a rule", "operationId": "ruleDetails", "summary": "Get a rule details", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET 'https://rudder.example.com/rudder/api/latest/rules/06ba8940-ed6c-4102-ba46-93d640a64c36'" } ] }, "post": { "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "parameters": [ { "description": "Id of the target rule", "format": "uuid", "in": "path", "name": "ruleId", "required": true, "type": "string" }, { "description": "The parent category id.", "format": "uuid", "in": "formData", "name": "category", "type": "string" }, { "collectionFormat": "csv", "description": "Directives linked to the rule", "in": "formData", "items": { "description": "Directive id", "type": "string" }, "name": "directives", "type": "array" }, { "description": "Rule name", "in": "formData", "name": "displayName", "type": "string" }, { "description": "Is the rule enabled", "in": "formData", "name": "enabled", "type": "boolean" }, { "description": "Rule id", "format": "uuid", "in": "formData", "name": "id", "type": "string" }, { "description": "Rule documentation", "in": "formData", "name": "longDescription", "type": "string" }, { "description": "One line rule description", "in": "formData", "name": "shortDescription", "type": "string" }, { "description": "If true it is an internal Rudder rule", "in": "formData", "name": "system", "type": "boolean" }, { "collectionFormat": "csv", "in": "formData", "items": { "example": { "customer": "MyCompany" }, "properties": { "name": { "description": "Value of the `name` key", "example": "value", "type": "string" } }, "type": "object" }, "name": "tags", "type": "array" }, { "collectionFormat": "csv", "description": "Groups linked to the rule", "in": "formData", "items": { "description": "Group id", "type": "string" }, "name": "targets", "type": "array" } ], "responses": { "200": { "description": "Rules information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "updateRule" ], "type": "string" }, "data": { "properties": { "rules": { "items": { "$ref": "#/definitions/rule-with-category" }, "type": "array" } }, "required": [ "rules" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Rules" ], "description": "Update the details of a rule", "operationId": "updateRule", "summary": "Update a rule details", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST 'https://rudder.example.com/rudder/api/latest/rules/17dadf50-6056-4c8b-a935-6b97d14b89a7' --data \"displayName=Name of rule\"" } ] } }, "/scaleoutrelay/promote/{nodeId}": { "post": { "produces": [ "application/json" ], "parameters": [ { "description": "Id of the target node", "format": "uuid (or \"root\")", "in": "path", "name": "nodeId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Promote response", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "promoteToRelay" ], "type": "string" }, "data": { "description": "Success or error message", "example": "17dadf50-6056-4c8b-a935-6b97d14b89a7", "type": "string" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "action", "result", "data" ], "type": "object" } } }, "tags": [ "🧩 Scale out Relay" ], "description": "Promote a node to relay", "operationId": "promoteToRelay", "summary": "Promote a node to relay", "x-code-samples": [ { "lang": "curl", "source": "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'" } ] } }, "/settings": { "get": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Settings", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "getAllSettings" ], "type": "string" }, "data": { "description": "Information about the setting", "properties": { "settings": { "properties": { "allowed_networks": { "description": "List of allowed networks for each policy server (root and relays)", "items": { "properties": { "allowed_networks": { "description": "List of allowed networks", "items": { "description": "Allowed network (`0.0.0.0/0` for no restriction `a.b.c.d/32` for one IP)", "example": "192.168.40.0/24", "format": "CIDR network", "type": "string" }, "type": "array" }, "id": { "description": "Rudder id of the policy server", "example": "root", "type": "string" } }, "type": "object" }, "type": "array" }, "change_message_prompt": { "description": "Explanation to display", "example": "Please provide a reason for this change", "type": "string" }, "display_recent_changes_graphs": { "description": "Display changes graphs", "example": true, "type": "boolean" }, "enable_change_message": { "description": "Enable change audit logs", "example": true, "type": "boolean" }, "enable_change_request": { "description": "Enable Change Requests", "example": false, "type": "boolean" }, "enable_javascript_directives": { "description": "Enable script evaluation in Directives", "example": "enabled", "type": "string" }, "enable_self_deployment": { "description": "Allow self deployment", "example": true, "type": "boolean" }, "enable_self_validation": { "description": "Allow self validation", "example": true, "type": "boolean" }, "first_run_hour": { "description": "First agent run time - hour", "example": 0, "type": "integer" }, "first_run_minute": { "description": "First agent run time - minute", "example": 0, "type": "integer" }, "global_policy_mode": { "description": "Define the default setting for global policy mode", "enum": [ "enforce", "audit" ], "example": "enforce", "type": "string" }, "global_policy_mode_overridable": { "description": "Allow overrides on this default setting", "example": true, "type": "boolean" }, "heartbeat_frequency": { "description": "Send heartbeat every heartbeat_frequency runs (only on **changes-only** compliance mode)", "example": 10, "type": "integer" }, "log_all_reports": { "description": "Log all reports received to `/var/log/rudder/reports/all.log`", "example": true, "type": "boolean" }, "mandatory_change_message": { "description": "Make message mandatory", "example": false, "type": "boolean" }, "modified_file_ttl": { "description": "Number of days to retain modified files", "example": 7, "type": "integer" }, "node_accept_duplicated_hostname": { "default": false, "description": "Allow acceptation of a pending node when another one with the same hostname is already accepted", "example": false, "type": "boolean" }, "node_onaccept_default_policyMode": { "description": "Default policy mode for accepted node", "enum": [ "default", "enforce", "audit" ], "example": "default", "type": "string" }, "node_onaccept_default_state": { "description": "Set default state for node when they are accepted within Rudder", "enum": [ "enabled", "ignored", "empty-policies", "initializing", "preparing-eol" ], "example": "enabled", "type": "string" }, "output_file_ttl": { "description": "Number of days to retain agent output files", "example": 7, "type": "integer" }, "relay_server_synchronization_method": { "description": "Method used to synchronize data between server and relays, either \"classic\" (agent protocol, default), \"rsync\" (use rsync to synchronize, that you'll need to be manually set up), or \"disabled\" (use third party system to transmit data)", "enum": [ "classic", "rsync", "disabled" ], "example": "classic", "type": "string" }, "relay_server_synchronize_policies": { "description": "If **rsync** is set as a synchronization method, use rsync to synchronize policies between Rudder server and relays. If false, you'll have to synchronize policies yourself.", "example": true, "type": "boolean" }, "relay_server_synchronize_shared_files": { "description": "If **rsync** is set as a synchronization method, use rsync to synchronize shared files between Rudder server and relays. If false, you'll have to synchronize shared files yourself.", "type": "boolean" }, "reporting_mode": { "description": "Compliance reporting mode", "enum": [ "full-compliance", "changes-only", "reports-disabled" ], "example": "full-compliance", "type": "string" }, "require_time_synchronization": { "description": "Require time synchronization between nodes and policy server", "example": true, "type": "boolean" }, "rsyslog_reporting_protocol": { "description": "Protocol used for syslog communication between node and server", "enum": [ "TCP", "UDP" ], "example": "UDP", "type": "string" }, "rudder_compute_changes": { "default": true, "description": "Compute list of changes (repaired reports) per rule", "type": "boolean" }, "rudder_generation_compute_dyngroups": { "default": true, "description": "Recompute all dynamic groups at the start of policy generation", "type": "boolean" }, "rudder_generation_continue_on_error": { "default": false, "description": "Policy generation continues on error during NodeConfiguration evaluation", "type": "boolean" }, "rudder_generation_js_timeout": { "default": 30, "description": "Policy generation JS evaluation of directive parameter timeout in seconds", "type": "integer" }, "rudder_generation_max_parallelism": { "default": "0.5", "description": "Set the policy generation parallelism, either as an number of thread (i.e. 4), or a multiplicative of the number of core (x0.5)", "type": "string" }, "rudder_report_protocol_default": { "description": "Default reporting protocol used", "enum": [ "HTTPS", "SYSLOG" ], "example": "HTTPS", "type": "string" }, "rudder_save_db_compliance_details": { "default": false, "description": "Store all compliance details in database", "type": "boolean" }, "rudder_save_db_compliance_levels": { "default": true, "description": "Store all compliance levels in database", "type": "boolean" }, "run_frequency": { "description": "Agent run schedule - time between agent runs (in minutes)", "example": 5, "type": "integer" }, "send_metrics": { "description": "Send anonymous usage statistics", "example": "not defined", "type": "string" }, "splay_time": { "description": "Maximum delay after scheduled run time (random interval)", "example": 5, "type": "integer" }, "syslog_protocol_disabled": { "description": "Completely disable syslog protocol", "example": true, "type": "boolean" }, "unexpected_allows_duplicate": { "default": true, "description": "Ignore duplicated compliance reports", "example": true, "type": "boolean" }, "unexpected_unbound_var_values": { "default": true, "description": "Allows multiple reports for configuration based on a multivalued variable", "type": "boolean" } } } }, "required": [ "settings" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Settings" ], "description": "Get the current value of all the settings", "operationId": "getAllSettings", "summary": "List all settings", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" https://rudder.example.com/rudder/api/latest/settings" } ] } }, "/settings/{settingId}": { "get": { "produces": [ "application/json" ], "parameters": [ { "description": "Id of the setting to set", "in": "path", "name": "settingId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Settings", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "getSetting" ], "type": "string" }, "data": { "description": "Information about the setting", "properties": { "settingId": { "description": "Id and value of the property", "example": "value", "type": "string" } }, "required": [ "settings" ], "type": "object" }, "id": { "description": "Id of the setting", "example": "global_policy_mode", "type": "string" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data", "id" ], "type": "object" } } }, "tags": [ "Settings" ], "description": "Get the current value of a specific setting", "operationId": "getSetting", "summary": "Get the value of a setting", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" https://rudder.example.com/rudder/api/latest/settings/run_frequency" } ] }, "post": { "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "parameters": [ { "description": "Id of the setting to set", "in": "path", "name": "settingId", "required": true, "type": "string" }, { "description": "New value of the setting", "in": "formData", "name": "value", "type": "string" } ], "responses": { "200": { "description": "Settings", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "modifySetting" ], "type": "string" }, "data": { "description": "Information about the setting", "properties": { "settingId": { "description": "Id and value of the property", "example": "value", "type": "string" } }, "required": [ "settings" ], "type": "object" }, "id": { "description": "Id of the setting", "example": "global_policy_mode", "type": "string" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data", "id" ], "type": "object" } } }, "tags": [ "Settings" ], "description": "Set the current value of a specific setting", "operationId": "modifySetting", "summary": "Set the value of a setting", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST https://rudder.example.com/rudder/api/latest/settings/global_policy_mode_overridable --data \"value=true\"" } ] } }, "/system/archives/{archiveKind}": { "get": { "produces": [ "application/json" ], "parameters": [ { "description": "Type of archive to make", "enum": [ "full", "groups", "rules", "directives", "parameters" ], "in": "path", "name": "archiveKind", "required": true, "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "properties": { "action": { "description": "The kind of the archive", "enum": [ "archiveFull", "archiveGroups", "archiveRules", "archiveDirectives", "archiveParameters" ], "example": "archiveFull", "type": "string" }, "data": { "properties": { "full": { "items": { "properties": { "commiter": { "example": "Rudder system account", "type": "string" }, "gitCommit": { "example": "546de1b211ecc5b7ca295abac2191bc6bb05d44e", "format": "hash", "type": "string" }, "id": { "example": "2019-09-17_16-06-15.255", "type": "string" } }, "required": [ "commiter", "gitCommit", "id" ], "type": "object" }, "type": "array" } }, "required": [ "full" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "System" ], "description": "List configuration archives", "operationId": "listArchives", "summary": "List archives", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" https://rudder.example.com/rudder/api/latest/system/archives/full" } ] }, "post": { "produces": [ "application/json" ], "parameters": [ { "description": "Type of archive to make", "enum": [ "full", "groups", "rules", "directives", "parameters" ], "in": "path", "name": "archiveKind", "required": true, "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "properties": { "action": { "description": "The kind of the archive", "enum": [ "archiveFull", "archiveGroups", "archiveRules", "archiveDirectives", "archiveParameters" ], "example": "archiveFull", "type": "string" }, "data": { "properties": { "full": { "properties": { "commiter": { "example": "Rudder system account", "type": "string" }, "gitCommit": { "example": "546de1b211ecc5b7ca295abac2191bc6bb05d44e", "format": "hash", "type": "string" }, "id": { "example": "2019-09-17_16-06-15.255", "type": "string" } }, "required": [ "commiter", "gitCommit", "id" ], "type": "object" } }, "required": [ "full" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "System" ], "description": "Create new archive of the given kind", "operationId": "createArchive", "summary": "Create an archive", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST https://rudder.example.com/rudder/api/latest/system/archives/full" } ] } }, "/system/archives/{archiveKind}/restore/{archiveRestoreKind}": { "post": { "produces": [ "application/json" ], "parameters": [ { "description": "Type of archive to make", "enum": [ "full", "groups", "rules", "directives", "parameters" ], "in": "path", "name": "archiveKind", "required": true, "type": "string" }, { "description": "What archive to restore (latest archive, latest commit in configuration repository, or archive with ID as given by listArchive)", "enum": [ "latestArchive", "latestCommit", "archive ID" ], "in": "path", "name": "archiveRestoreKind", "required": true, "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "properties": { "action": { "description": "The kind of the archive", "enum": [ "restoreFullLatestArchive", "restoreGroupLatestArchive", "restoreRulesLatestArchive", "restoreDirectivesLatestArchive", "restoreParametersLatestArchive", "restoreFullLatestCommit", "restoreGroupLatestCommit", "restoreRulesLatestCommit", "restoreDirectivesLatestCommit", "restoreParametersLatestCommit", "archiveFullDateRestore", "archiveGroupDateRestore", "archiveRulesDateRestore", "archiveDirectivesDateRestore", "archiveParametersDateRestore" ], "example": "archirestoreFullLatestCommitveFull", "type": "string" }, "data": { "properties": { "parameters": { "example": "Started", "type": "string" }, "directive": { "example": "Started", "type": "string" }, "full": { "example": "Started", "type": "string" }, "groups": { "example": "Started", "type": "string" }, "rules": { "example": "Started", "type": "string" } }, "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "System" ], "description": "Restore an archive of the given kind for the given moment", "operationId": "restoreArchive", "summary": "Restore an archive", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST https://rudder.example.com/rudder/api/latest/system/archives/full/restore/latestCommit" } ] } }, "/system/archives/{archiveKind}/zip/{commitId}": { "get": { "produces": [ "application/octet-stream" ], "parameters": [ { "description": "Type of archive to make", "enum": [ "full", "groups", "rules", "directives", "parameters" ], "in": "path", "name": "archiveKind", "required": true, "type": "string" }, { "description": "commit ID of the archive to get as a ZIP file", "in": "path", "name": "commitId", "required": true, "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "format": "binary", "type": "string" } } }, "tags": [ "System" ], "description": "Get an archive of the given kind as a zip", "operationId": "getZipArchive", "summary": "Get an archive as a ZIP", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET https://rudder.example.com/rudder/api/latest/system/archives/full/zip/cad7d5f0729f06d22878b99869b8d43629e05a78 -o full-archive.zip" } ] } }, "/system/info": { "get": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Service information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "getSystemInfo" ], "type": "string" }, "data": { "description": "Information about the service", "properties": { "rudder": { "properties": { "build-time": { "example": "2019-03-25T10:11:23.000Z", "format": "date", "type": "string" }, "full-version": { "example": "6.0.4", "format": "X.Y.Z", "type": "string" }, "major-version": { "example": "6.0", "format": "X.Y", "type": "string" } }, "required": [ "major-version", "full-version", "build-time" ] } }, "required": [ "rudder" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "System" ], "description": "Get information about the server version", "operationId": "getSystemInfo", "summary": "Get server information", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" https://rudder.example.com/rudder/api/latest/system/info" } ] } }, "/system/reload": { "post": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Service reload", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "reloadAll" ], "type": "string" }, "data": { "properties": { "groups": { "enum": [ "Started" ], "type": "string" }, "techniques": { "enum": [ "Started" ], "type": "string" } }, "required": [ "groups", "techniques" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "System" ], "description": "Reload both techniques and dynamic groups", "operationId": "reloadAll", "summary": "Reload both techniques and dynamic groups", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST 'https://rudder.example.com/rudder/api/latest/system/reload'" } ] } }, "/system/status": { "get": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Service status", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "getStatus" ], "type": "string" }, "data": { "description": "Status of the service", "properties": { "global": { "enum": [ "OK" ], "type": "string" } }, "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "System" ], "description": "Get information about current server status", "operationId": "getStatus", "summary": "Get server status", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" https://rudder.example.com/rudder/api/latest/system/status" } ] } }, "/system/update/policies": { "post": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Success", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "updatePolicies" ], "type": "string" }, "data": { "properties": { "policies": { "enum": [ "Started" ], "type": "string" } }, "required": [ "policies" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "System" ], "description": "Update configuration policies if needed", "operationId": "updatePolicies", "summary": "Trigger update of policies", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST 'https://rudder.example.com/rudder/api/latest/system/update/policies'" } ] } }, "/techniques": { "get": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Techniques information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "listTechniques" ], "type": "string" }, "data": { "properties": { "techniques": { "$ref": "#/definitions/techniques" } }, "required": [ "techniques" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Techniques" ], "description": "List all technique with their versions", "operationId": "listTechniques", "summary": "List all techniques", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET https://rudder.example.com/rudder/api/latest/techniques" } ] } }, "/techniques/{techniqueName}/directives": { "get": { "produces": [ "application/json" ], "parameters": [ { "description": "Technique name", "in": "path", "name": "techniqueName", "required": true, "type": "string" } ], "responses": { "200": { "description": "Techniques information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "listTechniquesDirectives" ], "type": "string" }, "data": { "properties": { "directives": { "items": { "$ref": "#/definitions/directive" }, "type": "array" } }, "required": [ "directives" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Techniques" ], "description": "List all directives based on all version of a technique", "operationId": "listTechniquesDirectives", "summary": "List all directives based on a technique", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET https://rudder.example.com/rudder/api/latest/techniques/checkGenericFileContent/directives" } ] } }, "/techniques/{techniqueName}/{techniqueVersion}/directives": { "get": { "produces": [ "application/json" ], "parameters": [ { "description": "Technique name", "in": "path", "name": "techniqueName", "required": true, "type": "string" }, { "description": "Technique version", "in": "path", "name": "techniqueVersion", "required": true, "type": "string" } ], "responses": { "200": { "description": "Techniques information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "listTechniqueDirectives" ], "type": "string" }, "data": { "properties": { "directives": { "items": { "$ref": "#/definitions/directive" }, "type": "array" } }, "required": [ "directives" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "Techniques" ], "description": "List all directives based on a version of a technique", "operationId": "listTechniqueVersionDirectives", "summary": "List all directives based on a version of a technique", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET https://rudder.example.com/rudder/api/latest/techniques/checkGenericFileContent/6.0/directives" } ] } }, "/usermanagement": { "post": { "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "parameters": [ { "description": "If you want to provide hashed password set this propertie to `true` otherwise we will hash the plain password and store the hash", "enum": [ false, true ], "in": "formData", "name": "isPreHahed", "type": "boolean" }, { "description": "this password will be hashed for you if the `isPreHashed` is set on false", "in": "formData", "name": "password", "type": "string" }, { "collectionFormat": "csv", "description": "Defined user's permissions", "in": "formData", "items": { "example": "user", "type": "string" }, "name": "role", "type": "array" }, { "in": "formData", "name": "username", "type": "string" } ], "responses": { "200": { "description": "Updated", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "addUser" ], "type": "string" }, "data": { "properties": { "addedUser": { "properties": { "password": { "description": "this password will be hashed for you if the `isPreHashed` is set on false", "example": "passwdWillBeStoredHashed", "type": "string" }, "role": { "description": "defined user's permissions", "items": { "example": "user", "type": "string" }, "type": "array" }, "username": { "example": "John Doe", "type": "string" } }, "type": "object" } }, "required": [ "addedUser" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 User Management" ], "description": "Add a new user", "operationId": "addUser", "summary": "Add user", "x-code-samples": [ { "lang": "curl", "source": "add.json:\n\n{\n\t\"isPreHashed\" : false,\n\t\"username\" : \"John Doe\",\n \"password\" : \"passwdWillBeStoredHashed\",\n\t\"role\" : [\"user\"]\n}\n\ncurl --header \"X-API-Token: yourToken\" --request POST https://rudder.example.com/rudder/api/latest/usermanagement --header \"Content-type: application/json\" --data @add.json\n\n" } ] } }, "/usermanagement/roles": { "get": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Roles informations", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "getRole" ], "type": "string" }, "data": { "items": { "properties": { "id": { "description": "Name of the role", "enum": [ "inventory", "compliance", "administrator", "etc" ], "type": "string" }, "rights": { "description": "Role's rights", "items": { "enum": [ "node_read", "userAccount_all" ], "type": "string" }, "type": "array" } }, "required": [ "id", "rights" ], "type": "object" }, "type": "array" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 User Management" ], "description": "Get all available roles and their rights", "operationId": "getRole", "summary": "List all roles", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET 'https://rudder.example.com/rudder/api/latest/usermanagement/roles'" } ] } }, "/usermanagement/update/{username}": { "post": { "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "parameters": [ { "description": "Username of an user (unique)", "in": "path", "name": "username", "required": true, "type": "string" }, { "description": "If you want to provide hashed password set this propertie to `true` otherwise we will hash the plain password and store the hash", "enum": [ false, true ], "in": "formData", "name": "isPreHahed", "type": "boolean" }, { "description": "this password will be hashed for you if the `isPreHashed` is set on false", "in": "formData", "name": "password", "type": "string" }, { "collectionFormat": "csv", "description": "Defined user's permissions", "in": "formData", "items": { "example": "user", "type": "string" }, "name": "role", "type": "array" }, { "in": "formData", "name": "username", "type": "string" } ], "responses": { "200": { "description": "Updated", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "updateUser" ], "type": "string" }, "data": { "properties": { "updatedUser": { "properties": { "password": { "description": "New password given", "example": "Titi", "type": "string" }, "role": { "description": "defined user's permissions", "items": { "example": "user", "type": "string" }, "type": "array" }, "username": { "description": "New Username", "example": "Titi", "type": "string" } }, "required": [ "username", "password", "role" ], "type": "object" } }, "required": [ "updatedUser" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 User Management" ], "description": "Rename, change password (pre-hashed or not) and change permission of an user. If a parameter is empty, it will be ignored.", "operationId": "updateUser", "summary": "Update user's infos", "x-code-samples": [ { "lang": "curl", "source": "update.json:\n\n{\n\t\"isPreHashed\" : false,\n\t\"username\" : \"\",\n \"password\" : \"Safer password\",\n\t\"role\" : [\"user\", \"deployer\", \"inventory\"]\n}\n\ncurl --header \"X-API-Token: yourToken\" --request PUT https://rudder.example.com/rudder/api/latest/usermanagement/Toto --header \"Content-type: application/json\" --data @update.json\n\n" } ] } }, "/usermanagement/users": { "get": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Users information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "getUserInfo" ], "type": "string" }, "data": { "properties": { "digest": { "enum": [ "BCRYPT", "SHA512", "SHA256", "SHA1", "MD5" ], "type": "string" }, "users": { "items": { "$ref": "#/definitions/users" }, "type": "array" } }, "required": [ "digest", "users" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 User Management" ], "description": "Get the list of all present users and their permissions", "operationId": "getUserInfo", "summary": "List all users", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET 'https://rudder.example.com/rudder/api/latest/usermanagement/users'" } ] } }, "/usermanagement/users/reload": { "get": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Reload information", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "reloadUserConf" ], "type": "string" }, "data": { "properties": { "reload": { "properties": { "status": { "example": "Done", "type": "string" } }, "required": [ "status" ], "type": "object" } }, "required": [ "reload" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 User Management" ], "description": "Reload the users from the file system, in the configuration file", "operationId": "reloadUserConf", "summary": "Reload user", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request POST 'https://rudder.example.com/rudder/api/latest/usermanagement/users/reload'" } ] } }, "/usermanagement/{username}": { "delete": { "produces": [ "application/json" ], "parameters": [ { "description": "Username of an user (unique)", "in": "path", "name": "username", "required": true, "type": "string" } ], "responses": { "200": { "description": "Deleted user", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "deleteUser" ], "type": "string" }, "data": { "properties": { "deletedUser": { "properties": { "username": { "description": "Username of the deleted user", "example": "Toto", "type": "string" } }, "required": [ "username" ], "type": "object" } }, "required": [ "deletedUser" ], "type": "object" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 User Management" ], "description": "Delete the user and his permissions", "operationId": "deleteUser", "summary": "Delete an user", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request DELETE 'https://rudder.example.com/rudder/api/latest/usermanagement/Toto'" } ] } }, "/users": { "get": { "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "List users", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "listUsers" ], "type": "string" }, "data": { "items": { "$ref": "#/definitions/validated-user" }, "type": "array" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 Change requests" ], "description": "List all validated and unvalidated users", "operationId": "listUsers", "summary": "List user", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request GET https://rudder.example.com/rudder/api/latest/users" } ] } }, "/validatedUsers": { "post": { "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "parameters": [ { "collectionFormat": "csv", "description": "list of user to put in validated list", "in": "formData", "items": { "example": "John Do", "type": "string" }, "name": "validatedUsers", "required": true, "type": "array" } ], "responses": { "200": { "description": "Updated", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "addUser" ], "type": "string" }, "data": { "$ref": "#/definitions/validated-user" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 Change requests" ], "description": "Add and remove user from validated users", "operationId": "saveWorkflowUser", "summary": "Update validated user list", "x-code-samples": [ { "lang": "curl", "source": "update.json:\n\n{\n\t\"validatedUsers\": [\"John Do\", \"Jane Doe\"]\n}\n\ncurl --header \"X-API-Token: yourToken\" --request POST https://rudder.example.com/rudder/api/latest/validatedUsers --header \"Content-type: application/json\" --data @update.json\n\n" } ] } }, "/validatedUsers/{username}": { "delete": { "produces": [ "application/json" ], "parameters": [ { "description": "Username of an user (unique)", "in": "path", "name": "username", "required": true, "type": "string" } ], "responses": { "200": { "description": "Removed user", "schema": { "properties": { "action": { "description": "The id of the action", "enum": [ "listUsers" ], "type": "string" }, "data": { "description": "the user removed from validated list", "example": "John Do", "type": "string" }, "result": { "description": "Result of the request", "enum": [ "success", "error" ], "type": "string" } }, "required": [ "result", "action", "data" ], "type": "object" } } }, "tags": [ "🧩 Change requests" ], "description": "The user is again subject to workflow validation", "operationId": "removeValidatedUser", "summary": "Remove an user from validated user list", "x-code-samples": [ { "lang": "curl", "source": "curl --header \"X-API-Token: yourToken\" --request DELETE https://rudder.example.com/rudder/api/latest/validatedUsers/John Do\n" } ] } } }, "definitions": { "agent-key": { "description": "Information about agent key or certificate", "properties": { "status": { "description": "Certification status of the security token (reset to `undefined` to trust a new certificate). If \"certified\", inventory signature check will be enforced", "enum": [ "certified", "undefined" ], "type": "string" }, "value": { "description": "Certificate (or public key for <6.0 agents) used by the agent. Be careful write a \"\\n\" after header line and before footer line, JSON does not keep formating in string.", "example": "-----BEGIN CERTIFICATE-----\nMIIFqDCC[...]3tALNn\n-----END CERTIFICATE-----", "format": "PEM", "type": "string" } }, "required": [ "value" ], "type": "object" }, "branding-conf": { "properties": { "barColor": { "$ref": "#/definitions/color" }, "displayBar": { "description": "Whether header bar is displayed or not", "type": "boolean" }, "displayBarLogin": { "description": "Whether header bar is displayed in loggin page or not", "type": "boolean" }, "displayLabel": { "description": "Whether header bar's label is displayed or not", "type": "boolean" }, "displayMotd": { "description": "Whether the message of the day is displayed in loggin page or not", "type": "boolean" }, "labelColor": { "$ref": "#/definitions/color" }, "labelText": { "description": "The header bar's label title", "example": "Production", "type": "string" }, "motd": { "description": "Message of the day in loggin page", "example": "Welcome, please sign in:", "type": "string" }, "smallLogo": { "$ref": "#/definitions/logo" }, "wideLogo": { "$ref": "#/definitions/logo" } }, "required": [ "displayBar", "displayLabel", "labelText", "barColor", "labelColor", "wideLogo", "smallLogo", "displayBarLogin", "displayMotd", "motd" ], "type": "object" }, "change-request": { "description": "Content of the change request", "properties": { "acceptable": { "example": true, "type": "boolean" }, "changes": { "properties": { "rules": { "items": { "properties": { "action": { "example": "modify Rule", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "created by": { "example": "Matthieu C.", "type": "string" }, "description": { "type": "string" }, "id": { "example": 42, "type": "integer" }, "name": { "example": "Remove unused security policy", "type": "string" }, "status": { "enum": [ "Deployed", "Pending deployment", "Cancelled", "Pending validation", "Open" ], "type": "string" } }, "type": "object" }, "color": { "properties": { "alpha": { "description": "percentage of opacity", "example": 0.5, "maximum": 1, "minimum": 0, "type": "number" }, "blue": { "description": "percentage of blue component", "example": 0.235, "maximum": 1, "minimum": 0, "type": "number" }, "green": { "description": "percentage of green component", "example": 0.01, "maximum": 1, "minimum": 0, "type": "number" }, "red": { "description": "percentage of red component", "example": 0.2, "maximum": 1, "minimum": 0, "type": "number" } }, "required": [ "red", "blue", "green", "alpha" ], "type": "object" }, "cveCheck": { "properties": { "cveId": { "description": "CVE id", "example": "CVE-2019-5953", "format": "cve id", "type": "string" }, "nodes": { "description": "Id of Nodes affected by this CVE", "items": { "description": "Node id", "type": "string" }, "type": "array" }, "packages": { "description": "packages affected by this CVE", "items": { "description": "Packages affected by this CVE", "properties": { "name": { "description": "Name of the package affected", "example": "libssh2-1", "type": "string" }, "version": { "description": "Version of the package affected", "example": "1.7.0-1", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "cveDetails": { "properties": { "cvssv2": { "description": "CVSS V2 of the CVE", "properties": { "baseScore": { "description": "CVSS V2 base score", "type": "integer" }, "vector": { "description": "CVSS V2 vector", "type": "string" } }, "type": "object" }, "cvssv3": { "description": "CVSS V3 of the CVE", "properties": { "baseScore": { "description": "CVSS V3 base score", "example": 9.8, "format": "float (0 to 10)", "type": "number" }, "baseSeverity": { "description": "CVSS V3 Severity", "enum": [ "critical", "high", "medium", "low", "none" ], "type": "string" }, "vector": { "description": "CVSS V3 vector", "example": "CVSS:3.0/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H", "type": "string" } }, "type": "object" }, "cweIds": { "description": "List of CWE (Common Weakness Enumeration) of the CVE", "items": { "description": "id of a CWE", "example": "CWE-119", "type": "string" }, "type": "array" }, "description": { "description": "CVE Description", "example": "Buffer overflow in GNU Wget 1.20.1 and earlier allows remote attackers to cause a denial-of-service (DoS) or may execute an arbitrary code via unspecified vectors.", "format": "date", "type": "string" }, "id": { "description": "CVE id", "example": "CVE-2019-5953", "format": "cve id", "type": "string" }, "lastModifiedDate": { "description": "last Date the CVE was modified", "example": "2019-07-02T23:15:00.000Z", "format": "date", "type": "string" }, "publishedDate": { "description": "Date the CVE was published", "example": "2019-05-17T16:29:00.000Z", "format": "date", "type": "string" } }, "type": "object" }, "datasource": { "properties": { "description": { "description": "Description of the goal of the data source to create.", "example": "Synchronize example data from the CMDB", "type": "string" }, "enabled": { "description": "Enable or disable data source.", "example": true, "type": "boolean" }, "id": { "description": "Unique identifier of the data source to create.", "example": "test-data-source", "type": "string" }, "name": { "description": "The human readable name of the data source to create.", "example": "Test data source", "type": "string" }, "runParameters": { "description": "Parameters to configure when the data source is fetched to update node properties.", "properties": { "onGeneration": { "description": "Trigger a fetch at the beginning of a policy generation", "example": true, "type": "boolean" }, "onNewNode": { "description": "Trigger a fetch when a new node is accepted, for that node", "example": true, "type": "boolean" }, "schedule": { "description": "Configure if data source should be fetch periodically", "properties": { "type": { "description": "`scheduled` enables periodic update, `notscheduled` disables them", "enum": [ "scheduled", "notscheduled" ], "example": "scheduled", "type": "string" } }, "type": "object" } }, "type": "object" }, "type": { "description": "Define and configure data source type.", "properties": { "parameters": { "description": "You can use Rudder variable expansion (`${rudder.node`, `${node.properties...}`)", "properties": { "checkSsl": { "description": "Check SSL certificate validity for https. Must be set to false for self-signed certificate", "example": true, "type": "boolean" }, "headers": { "description": "Represent HTTP headers for the query. Rudder expansion available.", "items": { "properties": { "name": { "description": "Name of the header", "example": "X-API-Key", "type": "string" }, "value": { "description": "Value of the header", "example": "05ce8e3d9df6", "type": "string" } }, "type": "object" }, "type": "array" }, "path": { "description": "JSON path (as defined in [the specification](https://github.com/jayway/JsonPath/), without the leading `$.`) to find the interesting sub-json or string/number/boolean value in the answer. Let empty to use the whole answer as value.", "type": "string" }, "requestMethod": { "description": "HTTP method to use to contact the URL.", "enum": [ "GET", "POST" ], "example": "GET", "type": "string" }, "requestMode": { "description": "Configure the strategy used to query the HTTP data source.", "properties": { "name": { "description": "Node by node strategy", "enum": [ "byNode" ], "example": "byNode", "type": "string" } }, "type": "object" }, "requestTimeout": { "description": "Timeout in seconds for each HTTP request", "example": 10, "type": "integer" }, "url": { "description": "URL to contact. Rudder expansion available.", "example": "http://jsonplaceholder.typicode.com/users/1", "type": "string" } }, "type": "object" }, "name": { "description": "Data source type name", "enum": [ "HTTP" ], "example": "HTTP", "type": "string" } }, "type": "object" }, "updateTimeout": { "description": "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.", "example": 30, "type": "integer" } }, "type": "object" }, "directive": { "properties": { "parameters": { "description": "Directive parameters (depends on the source technique)", "example": { "name": "sections", "sections": [ { "section": { "name": "File to manage", "sections": [ { "section": { "name": "File", "vars": [ { "var": { "name": "FILE_AND_FOLDER_MANAGEMENT_PATH", "value": "/root/test" } } ] } }, { "section": { "name": "File cleaning options", "vars": [ { "var": { "name": "FILE_AND_FOLDER_DELETION_DAYS", "value": "0" } }, { "var": { "name": "FILE_AND_FOLDER_DELETION_OPTION", "value": "none" } }, { "var": { "name": "FILE_AND_FOLDER_DELETION_PATTERN", "value": ".*" } } ] } }, { "section": { "name": "Permissions", "vars": [ { "var": { "name": "FILE_AND_FOLDER_MANAGEMENT_CHECK_PERMISSIONS", "value": "false" } }, { "var": { "name": "FILE_AND_FOLDER_MANAGEMENT_GROUP", "value": "" } }, { "var": { "name": "FILE_AND_FOLDER_MANAGEMENT_OWNER", "value": "" } }, { "var": { "name": "FILE_AND_FOLDER_MANAGEMENT_PERM", "value": "000" } }, { "var": { "name": "FILE_AND_FOLDER_MANAGEMENT_RECURSIVE", "value": "1" } } ] } }, { "section": { "name": "Post-modification hook", "vars": [ { "var": { "name": "FILE_AND_FOLDER_MANAGEMENT_POST_HOOK_COMMAND", "value": "" } }, { "var": { "name": "FILE_AND_FOLDER_MANAGEMENT_POST_HOOK_RUN", "value": "false" } } ] } } ], "vars": [ { "var": { "name": "FILE_AND_FOLDER_MANAGEMENT_ACTION", "value": "copy" } }, { "var": { "name": "FILE_AND_FOLDER_MANAGEMENT_SOURCE", "value": "/vagrant/node.sh" } }, { "var": { "name": "FILE_AND_FOLDER_MANAGEMENT_SYMLINK_ENFORCE", "value": "false" } } ] } } ] }, "type": "object" }, "tags": { "items": { "example": { "customer": "MyCompany" }, "properties": { "name": { "description": "Value of the `name` key", "example": "value", "type": "string" } }, "type": "object" }, "type": "array" }, "displayName": { "description": "Human readable name of the directive", "example": "91252ea2-feb2-412d-8599-c6945fee02c4", "type": "string" }, "enabled": { "description": "Is the directive enabled", "example": true, "type": "boolean" }, "id": { "description": "Directive id", "example": "91252ea2-feb2-412d-8599-c6945fee02c4", "format": "uuid", "type": "string" }, "longDescription": { "description": "Description of the technique (rendered as markdown)", "example": "# Documentation\n* [Ticket link](https://tickets.example.com/issues/3456)", "format": "markdown", "type": "string" }, "policyMode": { "description": "Policy mode of the directive", "enum": [ "enforce", "audit" ], "example": "audit", "type": "string" }, "priority": { "description": "Directive priority. `0` has highest priority.", "example": 5, "maximum": 10, "minimum": 0, "type": "integer" }, "shortDescription": { "description": "One line directive description", "example": "91252ea2-feb2-412d-8599-c6945fee02c4", "type": "string" }, "system": { "description": "If true it is an internal Rudder directive", "example": false, "type": "boolean" }, "techniqueName": { "description": "Directive id", "example": "userManagement", "type": "string" }, "techniqueVersion": { "description": "Directive id", "example": "8.0", "type": "string" } }, "type": "object" }, "directive-new": { "properties": { "parameters": { "description": "Directive parameters (depends on the source technique)", "example": { "name": "sections", "sections": [ { "section": { "name": "File to manage", "sections": [ { "section": { "name": "File", "vars": [ { "var": { "name": "FILE_AND_FOLDER_MANAGEMENT_PATH", "value": "/root/test" } } ] } }, { "section": { "name": "File cleaning options", "vars": [ { "var": { "name": "FILE_AND_FOLDER_DELETION_DAYS", "value": "0" } }, { "var": { "name": "FILE_AND_FOLDER_DELETION_OPTION", "value": "none" } }, { "var": { "name": "FILE_AND_FOLDER_DELETION_PATTERN", "value": ".*" } } ] } }, { "section": { "name": "Permissions", "vars": [ { "var": { "name": "FILE_AND_FOLDER_MANAGEMENT_CHECK_PERMISSIONS", "value": "false" } }, { "var": { "name": "FILE_AND_FOLDER_MANAGEMENT_GROUP", "value": "" } }, { "var": { "name": "FILE_AND_FOLDER_MANAGEMENT_OWNER", "value": "" } }, { "var": { "name": "FILE_AND_FOLDER_MANAGEMENT_PERM", "value": "000" } }, { "var": { "name": "FILE_AND_FOLDER_MANAGEMENT_RECURSIVE", "value": "1" } } ] } }, { "section": { "name": "Post-modification hook", "vars": [ { "var": { "name": "FILE_AND_FOLDER_MANAGEMENT_POST_HOOK_COMMAND", "value": "" } }, { "var": { "name": "FILE_AND_FOLDER_MANAGEMENT_POST_HOOK_RUN", "value": "false" } } ] } } ], "vars": [ { "var": { "name": "FILE_AND_FOLDER_MANAGEMENT_ACTION", "value": "copy" } }, { "var": { "name": "FILE_AND_FOLDER_MANAGEMENT_SOURCE", "value": "/vagrant/node.sh" } }, { "var": { "name": "FILE_AND_FOLDER_MANAGEMENT_SYMLINK_ENFORCE", "value": "false" } } ] } } ] }, "type": "object" }, "tags": { "items": { "example": { "customer": "MyCompany" }, "properties": { "name": { "description": "Value of the `name` key", "example": "value", "type": "string" } }, "type": "object" }, "type": "array" }, "displayName": { "description": "Human readable name of the directive", "example": "91252ea2-feb2-412d-8599-c6945fee02c4", "type": "string" }, "enabled": { "description": "Is the directive enabled", "example": true, "type": "boolean" }, "id": { "description": "Directive id", "example": "91252ea2-feb2-412d-8599-c6945fee02c4", "format": "uuid", "type": "string" }, "longDescription": { "description": "Description of the technique (rendered as markdown)", "example": "# Documentation\n* [Ticket link](https://tickets.example.com/issues/3456)", "format": "markdown", "type": "string" }, "priority": { "description": "Directive priority. `0` has highest priority.", "example": 5, "maximum": 10, "minimum": 0, "type": "integer" }, "shortDescription": { "description": "One line directive description", "example": "91252ea2-feb2-412d-8599-c6945fee02c4", "type": "string" }, "source": { "description": "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.", "example": "b9f6d98a-28bc-4d80-90f7-d2f14269e215", "format": "uuid", "type": "string" }, "system": { "description": "If true it is an internal Rudder directive", "example": false, "type": "boolean" }, "techniqueName": { "description": "Directive id", "example": "userManagement", "type": "string" }, "techniqueVersion": { "description": "Directive id", "example": "8.0", "type": "string" } }, "type": "object" }, "group": { "properties": { "description": { "description": "Group description", "example": "Documentation for the group", "type": "string" }, "displayName": { "description": "Name of the group", "example": "Ubuntu 18.04 nodes", "type": "string" }, "dynamic": { "default": true, "description": "Should the group be dynamically refreshed (if not, it is a static group)", "type": "boolean" }, "enabled": { "default": true, "description": "Enable or disable the group", "type": "boolean" }, "groupClass": { "items": { "description": "Conditions defined on nodes in the groups. There is one based on the group id, and one based on the group name.", "example": "group_ubuntu", "format": "condition", "type": "string" }, "type": "array" }, "id": { "default": "{autogenerated}", "description": "Group id", "example": "32d013f7-b6d8-46c8-99d3-016307fa66c0", "format": "uuid", "type": "string" }, "nodeIds": { "description": "List of nodes in the group", "items": { "description": "Node in the group", "example": "109142a2-40eb-4e6d-84b4-7ebe3670474c", "format": "uuid (or \"root\")", "type": "string" }, "type": "array" }, "properties": { "description": "Group properties", "items": { "properties": { "name": { "description": "Property name", "example": "os", "type": "string" }, "value": { "description": "Property value (can be a string or JSON object)", "example": "debian10", "format": "string or JSON" } }, "required": [ "name", "value" ], "type": "object" }, "type": "array" }, "query": { "description": "The criteria defining the group", "properties": { "composition": { "default": "and", "description": "Boolean operator to use between each `where` criteria.", "enum": [ "and", "or" ], "example": "and", "type": "string" }, "select": { "default": "node", "description": "What kind of data we want to include. Here we can get policy servers/relay by setting `nodeAndPolicyServer`. Only used if `where` is defined.", "type": "string" }, "where": { "description": "List of criteria", "items": { "properties": { "attribute": { "description": "Attribute to compare", "example": "OS", "type": "string" }, "comparator": { "description": "Comparator to use", "example": "eq", "type": "string" }, "objectType": { "description": "Type of the object", "example": "node", "type": "string" }, "value": { "description": "Value to compare against", "example": "Linux", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } }, "type": "object" }, "group-category": { "properties": { "description": { "description": "Group category description", "example": "Nodes by hardware provider", "type": "string" }, "id": { "default": "{autogenerated}", "description": "Group category id, only provide it when needed.", "example": "32d013f7-b6d8-46c8-99d3-016307fa66c0", "format": "uuid", "type": "string" }, "name": { "description": "Name of the group category", "example": "Hardware groups", "type": "string" }, "parent": { "description": "The parent category of the groups", "example": "b9f6d98a-28bc-4d80-90f7-d2f14269e215", "format": "uuid", "type": "string" } }, "required": [ "parent", "name" ], "type": "object" }, "group-category-update": { "properties": { "description": { "description": "Group category description", "example": "Nodes by hardware provider", "type": "string" }, "name": { "description": "Name of the group category", "example": "Hardware groups", "type": "string" }, "parent": { "description": "The parent category of the groups", "example": "b9f6d98a-28bc-4d80-90f7-d2f14269e215", "format": "uuid", "type": "string" } }, "required": [ "parent", "name" ], "type": "object" }, "group-new": { "properties": { "category": { "description": "Id of the new group's category", "example": "e17ecf6a-a9f2-44de-a97c-116d24d30ff4", "format": "uuid", "type": "string" }, "description": { "description": "Group description", "example": "Documentation for the group", "type": "string" }, "displayName": { "description": "Name of the group", "example": "Ubuntu 18.04 nodes", "type": "string" }, "dynamic": { "default": true, "description": "Should the group be dynamically refreshed (if not, it is a static group)", "type": "boolean" }, "enabled": { "default": true, "description": "Enable or disable the group", "type": "boolean" }, "id": { "default": "{autogenerated}", "description": "Group id, only provide it when needed.", "example": "32d013f7-b6d8-46c8-99d3-016307fa66c0", "format": "uuid", "type": "string" }, "properties": { "description": "Group properties", "items": { "properties": { "name": { "description": "Property name", "example": "os", "type": "string" }, "value": { "description": "Property value (can be a string or JSON object)", "example": "debian10", "format": "string or JSON" } }, "required": [ "name", "value" ], "type": "object" }, "type": "array" }, "query": { "description": "The criteria defining the group. If not provided, the group will be empty.", "properties": { "composition": { "default": "and", "description": "Boolean operator to use between each `where` criteria.", "enum": [ "and", "or" ], "example": "and", "type": "string" }, "select": { "default": "node", "description": "What kind of data we want to include. Here we can get policy servers/relay by setting `nodeAndPolicyServer`. Only used if `where` is defined.", "type": "string" }, "where": { "description": "List of criteria", "items": { "properties": { "attribute": { "description": "Attribute to compare", "example": "OS", "type": "string" }, "comparator": { "description": "Comparator to use", "example": "eq", "type": "string" }, "objectType": { "description": "Type of the object", "example": "node", "type": "string" }, "value": { "description": "Value to compare against", "example": "Linux", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "source": { "description": "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.", "example": "b9f6d98a-28bc-4d80-90f7-d2f14269e215", "format": "uuid", "type": "string" } }, "required": [ "displayName", "category" ], "type": "object" }, "group-update": { "properties": { "category": { "description": "Id of the new group's category", "example": "e17ecf6a-a9f2-44de-a97c-116d24d30ff4", "format": "uuid", "type": "string" }, "description": { "description": "Group description", "example": "Documentation for the group", "type": "string" }, "displayName": { "description": "Name of the group", "example": "Ubuntu 18.04 nodes", "type": "string" }, "dynamic": { "default": true, "description": "Should the group be dynamically refreshed (if not, it is a static group)", "type": "boolean" }, "enabled": { "default": true, "description": "Enable or disable the group", "type": "boolean" }, "query": { "description": "The criteria defining the group. If not provided, the group will be empty.", "properties": { "composition": { "default": "and", "description": "Boolean operator to use between each `where` criteria.", "enum": [ "and", "or" ], "example": "and", "type": "string" }, "select": { "default": "node", "description": "What kind of data we want to include. Here we can get policy servers/relay by setting `nodeAndPolicyServer`. Only used if `where` is defined.", "type": "string" }, "where": { "description": "List of criteria", "items": { "properties": { "attribute": { "description": "Attribute to compare", "example": "OS", "type": "string" }, "comparator": { "description": "Comparator to use", "example": "eq", "type": "string" }, "objectType": { "description": "Type of the object", "example": "node", "type": "string" }, "value": { "description": "Value to compare against", "example": "Linux", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } }, "type": "object" }, "logo": { "properties": { "enable": { "description": "Whether the wide logo is displayed or not", "type": "boolean" } }, "required": [ "enable" ], "type": "object" }, "node-add": { "items": { "properties": { "agentKey": { "$ref": "#/definitions/agent-key" }, "hostname": { "description": "The fully qualified name of the node", "example": "my.node.hostname.local", "type": "string" }, "id": { "description": "The Rudder node unique identifier in /opt/rudder/etc/uuid.hive", "example": "378740d3-c4a9-4474-8485-478e7e52db52", "type": "string" }, "ipAddresses": { "description": "an array of IPs.", "items": { "example": "192.168.180.90", "type": "string" }, "type": "array" }, "machineType": { "description": "The kind of machine for the node (use vm for a generic VM)", "enum": [ "vmware", "physical", "vm", "solariszone", "qemu", "xen", "aixlpar", "hyperv", "bsdjail" ], "type": "string" }, "os": { "$ref": "#/definitions/os" }, "policyMode": { "description": "The policy mode for the node. Can only be specified when status=accepted. If not specified, the default (global) mode will be used", "enum": [ "enforce", "audit" ], "type": "string" }, "policyServerId": { "description": "The policy server ID for that node. By default, \"root\"", "example": "root", "type": "string" }, "properties": { "description": "Node properties in \"key\":\"value\" format, where \"key\" is a string, and \"value\" is either a string, a json array, or a json object.", "properties": { "tags": { "items": { "enum": [ "some", "tags" ], "type": "string" }, "type": "array" }, "env": { "example": "prod", "type": "string" }, "vars": { "properties": { "var1": { "example": "value1", "type": "string" }, "vars2": { "example": "value2", "type": "string" } }, "type": "object" } }, "type": "object" }, "state": { "description": "Node lifecycle state. Can only be specified when status=accepted. If not specified, enable is used", "enum": [ "enable", "ignored", "empty-policies", "initializing", "preparing-eol" ], "type": "string" }, "status": { "description": "Target status of the node", "enum": [ "accepted", "pending" ], "type": "string" }, "timezone": { "$ref": "#/definitions/timezone" } }, "required": [ "id", "hostname", "status", "os", "machineType", "properties", "ipAddresses" ], "type": "object" }, "type": "array" }, "node-full": { "properties": { "accounts": { "description": "User accounts declared in the node", "items": { "description": "User present on the system", "example": "root", "type": "string" }, "type": "array" }, "architectureDescription": { "description": "Information about CPU architecture (32/64 bits)", "example": "x86_64", "type": "string" }, "bios": { "description": "BIOS information", "properties": { "description": { "description": "System provided description of the BIOS (long name)", "example": "FIXME", "type": "string" }, "editor": { "description": "BIOS editor", "example": "innotek GmbH", "type": "string" }, "name": { "description": "BIOS name", "example": "VirtualBox", "type": "string" }, "quantity": { "description": "Number of BIOS on the machine", "example": 1, "type": "integer" }, "releaseDate": { "description": "Release date of the BIOS", "example": "2006-12-01 00:00:00+0000", "type": "string" }, "version": { "description": "BIOS version", "example": "1.2.3", "type": "string" } }, "type": "object" }, "controllers": { "description": "Physical controller information", "items": { "properties": { "description": { "description": "System provided description of the controller", "type": "string" }, "manufacturer": { "description": "Controller manufacturer", "type": "string" }, "name": { "description": "Controller name", "type": "string" }, "quantity": { "description": "Quantity of that controller", "example": 1, "type": "integer" }, "type": { "description": "Controller type", "type": "string" } }, "type": "object" }, "type": "array" }, "description": { "description": "A human intended description of the node (not used)", "example": "", "type": "string" }, "environmentVariables": { "description": "Environment variables defined on the node in the context of the agent", "items": { "properties": { "name": { "description": "Environment variable name", "example": "LANG", "type": "string" }, "value": { "description": "Environment variable value", "example": "en_US.UTF-8", "type": "string" } }, "type": "object" }, "type": "array" }, "fileSystems": { "description": "File system declared on the node", "items": { "properties": { "description": { "description": "Description of the file system", "type": "string" }, "fileCount": { "description": "Number of files", "example": 1456, "type": "integer" }, "freeSpace": { "description": "Free space remaining", "example": 3487, "type": "integer" }, "mountPoint": { "description": "Mount point", "example": "/srv", "type": "string" }, "name": { "description": "Type of file system (`ext4`, `swap`, etc.)", "example": "ext4", "type": "string" }, "totalSpace": { "description": "Total space", "example": 208869, "type": "integer" } }, "type": "object" }, "type": "array" }, "hostname": { "description": "Fully qualified name of the node", "example": "node1.example.com", "type": "string" }, "id": { "description": "Unique id of the node", "example": "9a1773c9-0889-40b6-be89-f6504443ac1b", "format": "uuid (or \"root\")", "type": "string" }, "ipAddresses": { "description": "IP addresses of the node (IPv4 and IPv6)", "items": { "description": "IP of the node", "example": "192.168.23.45", "type": "string" }, "type": "array" }, "lastInventoryDate": { "description": "Date and time of the latest generated inventory, if one is available (node time). Up to API v11, format was: \"YYYY-MM-dd HH:mm\"", "example": "2020-02-29T10:11:32Z", "format": "date", "type": "string" }, "lastRunDate": { "description": "Date and time of the latest run, if one is available (node time). Up to API v11, format was: \"YYYY-MM-dd HH:mm\"", "example": "2020-02-29T14:48:28Z", "format": "date", "type": "string" }, "machine": { "description": "Information about the underlying machine", "properties": { "id": { "description": "Rudder unique identifier for the machine", "type": "string" }, "manufacturer": { "description": "Information about machine manufacturer", "example": "innotek GmbH", "type": "string" }, "provider": { "description": "In the case of VM, the VM technology", "example": "vbox", "type": "string" }, "serialNumber": { "description": "If available, a unique identifier provided by the machine", "example": "ece12459-2b90-49c9-ab1e-72e38f797421", "type": "string" }, "type": { "description": "Type of the machine", "enum": [ "Physical", "Virtual" ], "example": "Virtual", "type": "string" } }, "type": "object" }, "managementTechnology": { "description": "Management agents running on the node", "items": { "properties": { "capabilities": { "description": "List of agent capabilities", "items": { "description": "Special capacities of the agent, like parsing xml or yaml, support of advanced acl, etc.", "example": "xml", "type": "string" }, "type": "array" }, "name": { "description": "Agent name", "example": "Rudder", "type": "string" }, "nodeKind": { "description": "kind of node for the management engine, like `root`, `relay`, `node`, `root-component`", "example": "node", "type": "string" }, "rootComponents": { "description": "Roles fullfilled by the agent", "items": { "description": "A role that node fulfills in management technology", "example": "rudder-db", "type": "string" }, "type": "array" }, "version": { "description": "Agent version", "example": "6.0.3.release-1.EL.7", "type": "string" } }, "required": [ "name", "value" ], "type": "object" }, "type": "array" }, "managementTechnologyDetails": { "description": "Additional information about management technology", "properties": { "cfengineKeys": { "description": "Certificates used by the agent", "items": { "description": "Certificate (or public key for <6.0 agents) used by the agent", "example": "-----BEGIN CERTIFICATE-----\\nMIIFqDCC[...]3tALNn\\n-----END CERTIFICATE-----", "format": "PEM", "type": "string" }, "type": "array" }, "cfengineUser": { "description": "Local user account used by the agent", "example": "root", "type": "string" } }, "type": "object" }, "memories": { "description": "Memory slots", "items": { "description": "Memory slots", "properties": { "capacity": { "description": "Size of modules", "example": 2, "type": "integer" }, "caption": { "description": "Manufacturer provided information about the module", "type": "string" }, "description": { "description": "System provided description", "type": "string" }, "name": { "description": "Name of the memory slot or memory module", "type": "string" }, "quantity": { "description": "Number of modules in that slot", "example": 1, "type": "string" }, "serialNumber": { "description": "Serial number of the module", "type": "string" }, "slotNumber": { "description": "Slot number", "example": 3, "type": "integer" }, "speed": { "description": "Memory speed (frequency)", "example": 1066, "type": "integer" }, "type": { "description": "Memory slot type", "type": "string" } }, "type": "object" }, "type": "array" }, "networkInterfaces": { "description": "Detailed information about registered network interfaces on the node", "items": { "properties": { "dhcpServer": { "description": "DHCP server managing that network interface", "example": "192.168.34.5", "type": "string" }, "ipAddresses": { "description": "IP addresses of the network interface", "items": { "description": "IP address", "example": "192.168.76.4", "type": "string" }, "type": "array" }, "macAddress": { "description": "MAC address of the network interface", "example": "08:00:27:6f:5c:14", "type": "string" }, "mask": { "items": { "description": "Network interface mask", "example": "255.255.255.0", "format": "CIDR", "type": "string" }, "type": "array" }, "name": { "description": "Interface name (for ex \"eth0\")", "example": "eth0", "type": "string" }, "speed": { "description": "Information about synchronization speed", "example": "1000", "type": "string" }, "status": { "description": "network interface status (enabled or not, up or down)", "example": "Up", "type": "string" }, "type": { "description": "Information about the type of network interface", "example": "ethernet", "type": "string" } }, "type": "object" }, "type": "array" }, "os": { "description": "Information about the operating system", "properties": { "fullName": { "description": "Full operating system name", "example": "CentOS Linux release 7.6.1810 (Core)", "type": "string" }, "kernelVersion": { "description": "Version of the OS kernel", "example": "3.10.0-957.1.3.el7.x86_64", "type": "string" }, "name": { "description": "Operating system name (distribution on Linux, etc.)", "example": "Centos", "type": "string" }, "servicePack": { "description": "If relevant, the service pack of the OS", "example": "3", "type": "string" }, "type": { "description": "Family of the OS", "enum": [ "Windows", "Linux", "AIX", "FreeBSD" ], "example": "Linux", "type": "string" }, "version": { "description": "OS version", "example": "7.6.1810", "type": "string" } }, "required": [ "type", "name", "version", "fullName", "kernelVersion" ], "type": "object" }, "policyMode": { "description": "Rudder policy mode for the node (`default` follows the global configuration)", "enum": [ "enforce", "audit", "default" ], "example": "audit", "type": "string" }, "policyServerId": { "description": "Rudder policy server managing the node", "example": "root", "format": "uuid (or \"root\")", "type": "string" }, "ports": { "description": "Physical port information objects", "items": { "properties": { "description": { "description": "System provided description of the port", "type": "string" }, "name": { "description": "Port name", "type": "string" }, "quantity": { "description": "Quantity of similar ports", "example": 1, "type": "integer" }, "type": { "description": "Port type", "type": "string" } }, "type": "object" }, "type": "array" }, "processes": { "description": "Process running (at inventory time)", "items": { "description": "Process information", "properties": { "cpuUsage": { "description": "CPU used by the process (at inventory time)", "example": 1, "type": "integer" }, "description": { "description": "System provided description about the process", "type": "string" }, "memory": { "description": "Memory allocated to the process (at inventory time)", "example": 0.4000000059604645, "format": "float", "type": "number" }, "name": { "description": "Process name", "example": "/usr/sbin/httpd -DFOREGROUND", "type": "string" }, "pid": { "description": "PID of the process", "example": 3576, "type": "integer" }, "started": { "description": "Started date and time of the process", "example": "2020-02-29 00:24", "format": "date", "type": "string" }, "tty": { "description": "TTY to which the process is", "example": "?", "type": "string" }, "user": { "description": "User account who started the process", "example": "apache", "type": "string" }, "virtualMemory": { "description": "Virtual memory allocated to the process (at inventory time)", "example": 4380, "type": "integer" } }, "type": "object" }, "type": "array" }, "processors": { "description": "CPU information", "items": { "properties": { "arch": { "description": "CPU architecture", "example": "i386", "type": "string" }, "core": { "description": "Number of core for that CPU", "example": 1, "type": "integer" }, "cpuid": { "description": "Identifier of the CPU", "type": "string" }, "description": { "description": "System provided description of the CPU", "type": "string" }, "externalClock": { "description": "External clock used by the CPU", "type": "string" }, "familyName": { "description": "CPU family", "type": "string" }, "manufacturer": { "description": "CPU manufacturer", "example": "Intel", "type": "string" }, "model": { "description": "CPU model", "example": 158, "type": "integer" }, "name": { "description": "CPU name", "example": "Intel(R) Core(TM) i7-7700HQ CPU @ 2.80GHz", "type": "string" }, "quantity": { "description": "Number of CPU with these features", "example": 1, "type": "integer" }, "speed": { "description": "Speed (frequency) of the CPU", "example": 2800, "type": "integer" }, "stepping": { "description": "Stepping or power management information", "example": 9, "type": "integer" }, "thread": { "description": "Number of thread by core for the CPU", "example": 1, "type": "integer" } }, "type": "object" }, "type": "array" }, "properties": { "description": "Node properties (either set by user or filled by third party sources)", "items": { "properties": { "name": { "description": "Property name", "example": "datacenter", "type": "string" }, "value": { "description": "Property value (can be a string or JSON object)", "example": "AMS2", "format": "string or JSON" } }, "required": [ "name", "value" ], "type": "object" }, "type": "array" }, "ram": { "description": "Size of RAM in MB", "type": "integer" }, "slots": { "description": "Physical extension slot information", "items": { "properties": { "description": { "description": "System provided description of the slots", "type": "string" }, "name": { "description": "Slot name or identifier", "type": "string" }, "quantity": { "description": "Quantity of similar slots", "type": "integer" }, "status": { "description": "Slot status (used, powered, etc)", "type": "string" } }, "type": "object" }, "type": "array" }, "software": { "description": "Software installed on the node (can have thousands items)", "items": { "properties": { "description": { "description": "A description of the software", "example": "A library for getting files from web servers", "type": "string" }, "editor": { "description": "Editor of the software", "example": "CentOS", "type": "string" }, "license": { "description": "Information about the license", "properties": { "description": { "description": "License description", "type": "string" }, "expirationDate": { "description": "License expiration date", "format": "date", "type": "string" }, "name": { "description": "License name", "type": "string" }, "oem": { "description": "Is this an OEM license (and information)", "type": "string" }, "productId": { "description": "License product identifier", "type": "string" }, "productKey": { "description": "License key", "type": "string" } }, "type": "object" }, "name": { "description": "Name of the software (as reported by the node)", "example": "libcurl", "type": "string" }, "releaseDate": { "description": "Release date of the software", "format": "date", "type": "string" }, "version": { "description": "Version of the software", "example": "7.29.0-54.el7_7.2", "type": "string" } }, "type": "object" }, "type": "array" }, "sound": { "description": "Sound card information", "items": { "properties": { "description": { "description": "System provided description of the sound card", "type": "string" }, "name": { "description": "Sound card name", "type": "string" }, "quantity": { "description": "Quantity of similar sound cards", "example": 1, "type": "integer" } }, "type": "object" }, "type": "array" }, "status": { "description": "Status of the node", "enum": [ "pending", "accepted", "deleted" ], "example": "accepted", "type": "string" }, "storage": { "description": "Storage (disks) information objects", "items": { "properties": { "description": { "description": "System provided information about the storage", "type": "string" }, "firmware": { "description": "Storage firmware information", "example": "10", "type": "string" }, "manufacturer": { "description": "Storage manufacturer", "type": "string" }, "model": { "description": "Storage model", "example": "VBOXHARDDISK", "type": "string" }, "name": { "description": "Storage name", "example": "sda", "type": "string" }, "quantity": { "description": "Quantity of similar storage", "example": 1, "type": "integer" }, "serialNumber": { "description": "Storage serial number", "example": "000a1954", "type": "string" }, "size": { "description": "Storage size in MB", "example": 85899, "type": "integer" }, "type": { "description": "Storage type", "example": "disk", "type": "string" } }, "type": "object" }, "type": "array" }, "timezone": { "properties": { "name": { "description": "Timezone name", "example": "UTC", "type": "string" }, "offset": { "description": "Timezone offset to UTC", "example": "+0000", "format": "+/-difference", "type": "string" } }, "required": [ "name", "value" ], "type": "object" }, "videos": { "description": "Video card information", "items": { "properties": { "chipset": { "description": "information about video card chipset", "type": "string" }, "description": { "description": "System provided description for that video card", "type": "string" }, "memory": { "description": "Quantity of memory for that video card", "type": "string" }, "name": { "description": "Video card name", "type": "string" }, "quantity": { "description": "Quantity of similar video cards", "example": 1, "type": "integer" }, "resolution": { "description": "Resolution used by that video card at inventory time", "type": "string" } }, "type": "object" }, "type": "array" }, "virtualMachines": { "description": "Hosted virtual machine information", "items": { "properties": { "description": { "description": "System provided description of the hosted virtual machine", "type": "string" }, "memory": { "description": "Memory allocated to the hosted virtual machine", "type": "string" }, "name": { "description": "Name of the hosted virtual machine", "type": "string" }, "owner": { "description": "Owner of the hosted virtual machine", "type": "string" }, "status": { "description": "Status (up, starting, etc) of the hosted virtual machine", "type": "string" }, "subsystem": { "description": "Technology of the hosted virtual machine", "type": "string" }, "type": { "description": "Type of the hosted virtual machine", "type": "string" }, "uuid": { "description": "Unique identifier of the hosted virtual machine", "type": "string" }, "vcpu": { "description": "Number of virtual CPU allocated to the hosted virtual machine", "type": "string" } }, "type": "object" }, "type": "array" } }, "required": [ "id", "hostname", "status", "ipAddresses", "managementTechnology", "policyServerId", "properties" ], "type": "object" }, "node-settings": { "properties": { "agentKey": { "$ref": "#/definitions/agent-key" }, "policyMode": { "description": "In which mode the node will apply its configuration policy. Use `default` to use the global mode.", "enum": [ "audit", "enforce", "default" ], "example": "audit", "type": "string" }, "properties": { "items": { "properties": { "name": { "description": "Property name", "example": "datacenter", "type": "string" }, "value": { "description": "Property value (can be a string or JSON object)", "example": "AMS2", "format": "string or JSON" } }, "required": [ "name", "value" ], "type": "object" }, "type": "array" }, "state": { "description": "The node life cycle state. See [dedicated doc](https://docs.rudder.io/reference/current/usage/advanced_node_management.html#node-lifecycle) for more information.", "enum": [ "enabled", "ignored", "empty-policies", "initializing", "preparing-eol" ], "example": "enabled", "type": "string" } }, "type": "object" }, "os": { "properties": { "fullName": { "description": "The long description name of the os", "example": "Debian GNU/Linux 9 (stretch)", "type": "string" }, "name": { "description": "For Linux, a distribution, for Windows, the commercial name", "enum": [ "debian", "ubuntu", "redhat", "centos", "fedora", "suse", "oracle", "scientific", "slackware", "xp", "vista", "seven", "10", "2000", "2003", "2008 r2", "2012", "2012 r2", "2016" ], "type": "string" }, "servicePack": { "description": "a service pack informationnal string", "type": "string" }, "type": { "enum": [ "linux", "windows", "solaris", "aix", "freebsd", "unknown" ], "type": "string" }, "version": { "description": "A string representation of the version", "example": 9.5, "type": "string" } }, "required": [ "type", "name", "version", "fullName" ], "type": "object" }, "parameter": { "properties": { "description": { "description": "Description of the parameter", "example": "Default inform message put in footer of managed files by Rudder", "type": "string" }, "id": { "description": "Name of the parameter", "example": "rudder_file_edit_footer", "type": "string" }, "overridable": { "description": "Is the global parameter overridable by node", "example": false, "type": "boolean" }, "value": { "description": "Value of the parameter", "example": "### End of file managed by Rudder ###", "format": "string or JSON" } }, "required": [ "id" ], "type": "object" }, "rule": { "properties": { "tags": { "items": { "example": { "customer": "MyCompany" }, "properties": { "name": { "description": "Value of the `name` key", "example": "value", "type": "string" } }, "type": "object" }, "type": "array" }, "directives": { "description": "Directives linked to the rule", "items": { "description": "Directive id", "type": "string" }, "type": "array" }, "displayName": { "description": "Rule name", "example": "Security policy", "type": "string" }, "enabled": { "description": "Is the rule enabled", "example": true, "type": "boolean" }, "id": { "description": "Rule id", "example": "0c1713ae-cb9d-4f7b-abda-ca38c5d643ea", "format": "uuid", "type": "string" }, "longDescription": { "description": "Rule documentation", "example": "This rules should be applied to all Linux nodes required basic hardening", "type": "string" }, "shortDescription": { "description": "One line rule description", "example": "Baseline applying CIS guidelines", "type": "string" }, "system": { "description": "If true it is an internal Rudder rule", "example": false, "type": "boolean" }, "targets": { "description": "Groups linked to the rule", "items": { "description": "Group id", "type": "string" }, "type": "array" } }, "type": "object" }, "rule-category": { "properties": { "description": { "description": "Rules category description", "example": "Baseline applying CIS guidelines", "type": "string" }, "id": { "default": "{autogenerated}", "description": "Rule category id, only provide it when needed.", "example": "32d013f7-b6d8-46c8-99d3-016307fa66c0", "format": "uuid", "type": "string" }, "name": { "description": "Name of the rule category", "example": "Security policies", "type": "string" }, "parent": { "description": "The parent category of the rules", "example": "b9f6d98a-28bc-4d80-90f7-d2f14269e215", "format": "uuid", "type": "string" } }, "required": [ "parent", "name" ], "type": "object" }, "rule-category-update": { "properties": { "description": { "description": "Rules category description", "example": "Baseline applying CIS guidelines", "type": "string" }, "name": { "description": "Name of the rule category", "example": "Security policies", "type": "string" }, "parent": { "description": "The parent category of the rules", "example": "b9f6d98a-28bc-4d80-90f7-d2f14269e215", "format": "uuid", "type": "string" } }, "required": [ "parent", "name" ], "type": "object" }, "rule-new": { "properties": { "tags": { "items": { "example": { "customer": "MyCompany" }, "properties": { "name": { "description": "Value of the `name` key", "example": "value", "type": "string" } }, "type": "object" }, "type": "array" }, "category": { "description": "The parent category id. If provided, the new rule will be in this parent category", "example": "38e0c6ea-917f-47b8-82e0-e6a1d3dd62ca", "format": "uuid", "type": "string" }, "directives": { "description": "Directives linked to the rule", "items": { "description": "Directive id", "type": "string" }, "type": "array" }, "displayName": { "description": "Rule name", "example": "Security policy", "type": "string" }, "enabled": { "description": "Is the rule enabled", "example": true, "type": "boolean" }, "id": { "description": "Rule id", "example": "0c1713ae-cb9d-4f7b-abda-ca38c5d643ea", "format": "uuid", "type": "string" }, "longDescription": { "description": "Rule documentation", "example": "This rules should be applied to all Linux nodes required basic hardening", "type": "string" }, "shortDescription": { "description": "One line rule description", "example": "Baseline applying CIS guidelines", "type": "string" }, "source": { "description": "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.", "example": "b9f6d98a-28bc-4d80-90f7-d2f14269e215", "format": "uuid", "type": "string" }, "system": { "description": "If true it is an internal Rudder rule", "example": false, "type": "boolean" }, "targets": { "description": "Groups linked to the rule", "items": { "description": "Group id", "type": "string" }, "type": "array" } }, "type": "object" }, "rule-with-category": { "properties": { "tags": { "items": { "example": { "customer": "MyCompany" }, "properties": { "name": { "description": "Value of the `name` key", "example": "value", "type": "string" } }, "type": "object" }, "type": "array" }, "category": { "description": "The parent category id.", "example": "38e0c6ea-917f-47b8-82e0-e6a1d3dd62ca", "format": "uuid", "type": "string" }, "directives": { "description": "Directives linked to the rule", "items": { "description": "Directive id", "type": "string" }, "type": "array" }, "displayName": { "description": "Rule name", "example": "Security policy", "type": "string" }, "enabled": { "description": "Is the rule enabled", "example": true, "type": "boolean" }, "id": { "description": "Rule id", "example": "0c1713ae-cb9d-4f7b-abda-ca38c5d643ea", "format": "uuid", "type": "string" }, "longDescription": { "description": "Rule documentation", "example": "This rules should be applied to all Linux nodes required basic hardening", "type": "string" }, "shortDescription": { "description": "One line rule description", "example": "Baseline applying CIS guidelines", "type": "string" }, "system": { "description": "If true it is an internal Rudder rule", "example": false, "type": "boolean" }, "targets": { "description": "Groups linked to the rule", "items": { "description": "Group id", "type": "string" }, "type": "array" } }, "type": "object" }, "techniques": { "items": { "properties": { "name": { "description": "Technique name", "example": "userManagement", "type": "string" }, "versions": { "description": "Available versions for this technique", "items": { "description": "Technique version", "example": "6.0", "type": "string" }, "type": "array" } }, "type": "object" }, "type": "array" }, "timezone": { "description": "Timezone information of the node.", "properties": { "name": { "description": "The standard name of the timezone", "example": "CEST", "type": "string" }, "offset": { "description": "Timezone offset compared to UTC, in +/-HHMM format", "example": 128, "type": "string" } }, "required": [ "name", "offset" ], "type": "object" }, "users": { "properties": { "isPreHahed": { "description": "If you want to provide hashed password set this propertie to `true` otherwise we will hash the plain password and store the hash", "enum": [ false, true ], "type": "boolean" }, "password": { "description": "this password will be hashed for you if the `isPreHashed` is set on false", "example": "passwdWillBeStoredHashed", "type": "string" }, "role": { "description": "Defined user's permissions", "items": { "example": "user", "type": "string" }, "type": "array" }, "username": { "example": "John Doe", "type": "string" } }, "type": "object" }, "validated-user": { "description": "list of users with their workflow settings", "properties": { "isValidated": { "description": "whether the user's actions generate chanque-request or not", "type": "boolean" }, "userExists": { "description": "whether the user exists in file or not", "type": "boolean" }, "username": { "example": "John Do", "type": "string" } }, "required": [ "username", "isValidated", "userExists" ], "type": "object" } }, "securityDefinitions": { "API-Tokens": { "description": "Authenticating against the API is mandatory for every request, as sensitive information like inventories or configuration rules may get exposed. It is done using a dedicated API Account, than can be created in the web interface on the 'API Accounts' page located inside the Administration part.\n\n![API Tokens settings](assets/APISettings.png \"API Tokens settings\")\n\nAPI Accounts are not linked to standard user accounts, and currently give full administrative privileges: they must be secured adequately. Once you have created an API account, you get a token that will be needed to authenticate every request. This token is the API equivalent of a password, and must be secured just like a password would be.\n\nOn any call to the API, you will need to add a **X-API-Token** header to your request to authenticate:\n\n\n curl --request GET --header \"X-API-Token: yourToken\" https://rudder.example.com/rudder/api/latest/rules\n\n\nIf you perform any action (creation, update, deletion) using the API, the event log generated will record the API account as the user.", "in": "header", "name": "X-API-Token", "type": "apiKey" } }, "security": [ { "API-Tokens": [] } ], "tags": [ { "description": "Access compliance data", "name": "Compliance" }, { "description": "Rules management", "name": "Rules" }, { "description": "Directives management", "name": "Directives" }, { "description": "Techniques management", "name": "Techniques" }, { "description": "Groups management", "name": "Groups" }, { "description": "Nodes management", "name": "Nodes" }, { "description": "Inventory processing service", "name": "Inventories" }, { "description": "Global parameters", "name": "Parameters" }, { "description": "Server configuration", "name": "Settings" }, { "description": "Internal components and administration", "name": "System" }, { "description": "**Requires that the `changes-validation` plugin is installed on the server.**\n\nManage change requests.", "name": "🧩 Change requests" }, { "description": "**Requires that the `cve` plugin is installed on the server.**\n\nManage CVE plugins data and configuration.", "name": "🧩 CVE" }, { "description": "**Requires that the `datasources` plugin is installed on the server.**\n\nData sources plugin configuration.", "name": "🧩 Data sources" }, { "description": "**Requires that the `scale-out-relay` plugin is installed on the server.**\n\nManage relays.", "name": "🧩 Scale out Relay" }, { "description": "**Requires that the `create-node` plugin is installed on the server.**\n\nAdd new nodes.", "name": "🧩 Create Node" }, { "description": "**Requires that the `user-management` plugin is installed on the server.**\n\nManage users settings and configuration file.", "name": "🧩 User Management" }, { "description": "**Requires that the `branding` plugin is installed on the server.**\n\nManage web interface customization.", "name": "🧩 Branding" } ], "externalDocs": { "description": "Learn more about Rudder.", "url": "https://docs.rudder.io" }, "x-components": { "parameters": { "archive-kind": { "description": "Type of archive to make", "enum": [ "full", "groups", "rules", "directives", "parameters" ], "in": "path", "name": "archiveKind", "required": true, "type": "string" }, "change-request-id": { "description": "Change request id", "in": "path", "name": "changeRequestId", "required": true, "type": "integer" }, "compliance-level": { "default": 10, "description": "Number of depth level of compliance objects to display (1:rules, 2:directives, 3:components, 4:nodes, 5:values, 6:reports)", "in": "query", "name": "level", "type": "integer" }, "datasource-id": { "description": "Id of the data source", "in": "path", "name": "datasourceId", "required": true, "type": "string" }, "directive-id": { "description": "Id of the directive", "format": "uuid", "in": "path", "name": "directiveId", "required": true, "type": "string" }, "group-category-id": { "description": "Group category id", "format": "uuid", "in": "path", "name": "groupCategoryId", "required": true, "type": "string" }, "group-id": { "description": "Id of the group", "format": "uuid", "in": "path", "name": "groupId", "required": true, "type": "string" }, "include": { "default": "default", "description": "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.\n* **minimal** includes: `id`, `hostname` and `status`\n* **default** includes **minimal** plus `architectureDescription`, `description`, `ipAddresses`, `lastRunDate`, `lastInventoryDate`, `machine`, `os`, `managementTechnology`, `policyServerId`, `properties`, `policyMode `, `ram` and `timezone`\n* **full** includes: **default** plus `accounts`, `bios`, `controllers`, `environmentVariables`, `fileSystems`, `managementTechnologyDetails`, `memories`, `networkInterfaces`, `ports`, `processes`, `processors`, `slots`, `software`, `sound`, `storage`, `videos` and `virtualMachines`", "format": "comma-separated list", "in": "query", "name": "include", "type": "string" }, "node-composition": { "default": "and", "description": "Boolean operator to use between each `where` criteria.", "enum": [ "and", "or" ], "in": "query", "name": "composition", "type": "string" }, "node-id": { "description": "Id of the target node", "format": "uuid (or \"root\")", "in": "path", "name": "nodeId", "required": true, "type": "string" }, "node-info": { "content": { "application/json": { "schema": { "$ref": "#/definitions/node-add" } } }, "description": "Description of a node configuration", "in": "query", "name": "Node parameters" }, "node-query": { "content": { "application/json": { "schema": { "properties": { "composition": { "default": "and", "description": "Boolean operator to use between each `where` criteria.", "enum": [ "and", "or" ], "example": "and", "type": "string" }, "select": { "default": "node", "description": "What kind of data we want to include. Here we can get policy servers/relay by setting `nodeAndPolicyServer`. Only used if `where` is defined.", "type": "string" }, "where": { "description": "List of criteria", "items": { "properties": { "attribute": { "description": "Attribute to compare", "example": "OS", "type": "string" }, "comparator": { "description": "Comparator to use", "example": "eq", "type": "string" }, "objectType": { "description": "Type of the object", "example": "node", "type": "string" }, "value": { "description": "Value to compare against", "example": "Linux", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "The criterion you want to find for your nodes. Replaces the `where`, `composition` and `select` parameters in a single parameter.", "in": "query", "name": "query" }, "node-select": { "default": "node", "description": "What kind of data we want to include. Here we can get policy servers/relay by setting `nodeAndPolicyServer`. Only used if `where` is defined.", "in": "query", "name": "select", "type": "string" }, "node-where": { "content": { "application/json": { "schema": { "description": "List of criteria", "items": { "properties": { "attribute": { "description": "Attribute to compare", "example": "OS", "type": "string" }, "comparator": { "description": "Comparator to use", "example": "eq", "type": "string" }, "objectType": { "description": "Type of the object", "example": "node", "type": "string" }, "value": { "description": "Value to compare against", "example": "Linux", "type": "string" } }, "type": "object" }, "type": "array" } } }, "description": "The criterion you want to find for your nodes", "in": "query", "name": "where" }, "parameter-id": { "description": "Id of the parameter to manage", "in": "path", "name": "parameterId", "required": true, "type": "string" }, "rule-category-id": { "description": "Rule category id", "format": "uuid", "in": "path", "name": "ruleCategoryId", "required": true, "type": "string" }, "rule-id": { "description": "Id of the target rule", "format": "uuid", "in": "path", "name": "ruleId", "required": true, "type": "string" }, "setting-id": { "description": "Id of the setting to set", "in": "path", "name": "settingId", "required": true, "type": "string" }, "technique-name": { "description": "Technique name", "in": "path", "name": "techniqueName", "required": true, "type": "string" }, "technique-version": { "description": "Technique version", "in": "path", "name": "techniqueVersion", "required": true, "type": "string" }, "username": { "description": "Username of an user (unique)", "in": "path", "name": "username", "required": true, "type": "string" } }, "responses": { "agent-output": { "content": { "text/plain": { "schema": { "example": "Start execution with config [20200218-112602-11ce4f64]\nHostname M| State Technique Component Key Message 192.168.210.5 E| compliant Common ncf Initialization Configuration library initialization was correct 192.168.210.5 E| compliant Common Update Policy and configuration library are already up to date. No action required. [...]\n## Summary ##################################################################### 90 components verified in 15 directives\n => 62 components in Enforce mode\n -> 48 compliant\n -> 13 not-applicable\n -> 1 error\n => 28 components in Audit mode\n -> 15 compliant\n -> 3 not-applicable\n -> 10 non-compliant\nExecution time: 8.89s ################################################################################", "type": "string" } } }, "description": "Agent output" } } } }