Rudder API API

Overview

Download OpenAPI specification: [openapi.yml](openapi.yml) # Introduction Rudder exposes a REST API, enabling the user to interact with Rudder without using the webapp, for example in scripts or cronjobs. ## Versioning Each time the API is extended with new features (new functions, new parameters, new responses, ...), it will be assigned a new version number. This will allow you to keep your existing scripts (based on previous behavior). Versions will always be integers (no 2.1 or 3.3, just 2, 3, 4, ...) or `latest`. You can change the version of the API used by setting it either within the url or in a header: * the URL: each URL is prefixed by its version id, like `/api/version/function`. ```bash # Version 10 curl -X GET -H "X-API-Token: yourToken" https://rudder.example.com/rudder/api/10/rules # Latest curl -X GET -H "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/rules # Wrong (not an integer) => 404 not found curl -X GET -H "X-API-Token: yourToken" https://rudder.example.com/rudder/api/3.14/rules ``` * the HTTP headers. You can add the **X-API-Version** header to your request. The value needs to be an integer or `latest`. ```bash # Version 10 curl -X GET -H "X-API-Token: yourToken" -H "X-API-Version: 10" https://rudder.example.com/rudder/api/rules # Wrong => Error response indicating which versions are available curl -X GET -H "X-API-Token: yourToken" -H "X-API-Version: 3.14" https://rudder.example.com/rudder/api/rules ``` In the future, we may declare some versions as deprecated, in order to remove them in a later version of Rudder, but we will never remove any versions without warning, or without a safe period of time to allow migration from previous versions. <h4>Existing versions</h4> <table> <thead> <tr> <th style="width: 20%">Version</th> <th style="width: 20%">Rudder versions it appeared in</th> <th style="width: 70%">Description</th> </tr> </thead> <tbody> <tr> <td class="code">1</td> <td class="code">Never released (for internal use only)</td> <td>Experimental version</td> </tr> <tr> <td class="code">2 to 10 (deprecated)</td> <td class="code">4.3 and before</td> <td>These versions provided the core set of API features for rules, directives, nodes global parameters, change requests and compliance, rudder settings and system API</td> </tr> <tr> <td class="code">11</td> <td class="code">5.0</td> <td>New system API (replacing old localhost v1 api): status, maintenance operations and server behavior</td> </tr> <tr> <td class="code">12</td> <td class="code">6.0 and 6.1</td> <td>Node key management</td> </tr> <tr> <td class="code">13</td> <td class="code">6.2</td> <td><ul> <li>Node status endpoint</li> <li>System health check</li> <li>System maintenance job to purge software [that endpoint was back-ported in 6.1]</li> </ul></td> </tr> <tr> <td class="code">14</td> <td class="code">7.0</td> <td><ul> <li>Secret management</li> <li>Directive tree</li> <li>Improve techniques management</li> <li>Demote a relay</li> </ul></td> </tr> <tr> <td class="code">15</td> <td class="code">7.1</td> <td><ul> <li>Package updates in nodes</li> </ul></td> </tr> <tr> <td class="code">16</td> <td class="code">7.2</td> <td><ul> <li>Create node API included from plugin</li> <li>Configuration archive import/export</li> </ul></td> </tr> </tbody> </table> ## Response format All responses from the API are in the JSON format. ```json { "action": "The name of the called function", "id": "The ID of the element you want, if relevant", "result": "The result of your action: success or error", "data": "Only present if this is a success and depends on the function, it's usually a JSON object", "errorDetails": "Only present if this is an error, it contains the error message" } ``` * __Success__ responses are sent with the 200 HTTP (Success) code * __Error__ responses are sent with a HTTP error code (mostly 5xx...) ## HTTP method Rudder's REST API is based on the usage of [HTTP methods](http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.ht

Rudder API is a development API from rudder.example.local. Requests are authenticated with an API key. It is served over HTTPS. Its OpenAPI description documents 134 endpoints.

At a glance

Authentication

API key

HTTPS

Yes

CORS

Unknown

Category

Development

Base URL

https://rudder.example.local/rudder/api/latest/

Version

16

Endpoints

134

OpenAPI

Specification ↗

Spec updated

2023-03-06

Make a first request

Replace the placeholders; the documentation says exactly where credentials go.

curl -X GET "https://rudder.example.local/rudder/api/latest/api/changeRequests" \
  -H "Accept: application/json" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch("https://rudder.example.local/rudder/api/latest/api/changeRequests", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await response.json();
console.log(data);

import requests

response = requests.request(
    "GET",
    "https://rudder.example.local/rudder/api/latest/api/changeRequests",
    headers={
    "Accept": "application/json",
    "X-API-Key": "YOUR_API_KEY",
    },
    timeout=30,
)
print(response.json())

Endpoints

Questions