logo
API docs by Redocly

Rudder relay API (1)

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

Download OpenAPI specification: openapi.yml

Other documentation sources:

Introduction

Rudder relay exposes an internal API, enabling the agents and other services to interact with the relay.

A part of the API (everything but the System category) is exposed publicly on the relay at https://relay.example.com/rudder/relay-api/ (which is a reverse proxy of http://localhost:3030/rudder/relay-api/1/).

Authentication

The relay API is authenticated on a case-by-case basis:

  • Remote run is only accessible to requests from the IP of the relay's own policy server

  • Shared files checks file signature based on known public keys from nodes

  • Shared folder is only available to nodes in the authorized networks

  • System is only accessible to local clients and do not permit access to private information nor modification abilities

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, ...). You can change the version of the API used by setting in the URL: each URL is prefixed by its version id, like /relay-api/version/action. In the future, we may declare some versions as deprecated, in order to remove them in a later version of Rudder, but we will never remove any versions without warning, or without a safe period of time to allow migration from previous versions.

Existing versions:

Version Rudder version it appeared in Description
(none) 3.2 Unversioned API providing remote-run, shared-files and shared-folder
1 6.0 First relay API with a version

Response format

The System API and future endpoints use JSON with the following schema:

  {
    "action": The name of the called function,
    "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
  }

System

Internal relay service management

Get metrics

Get metrics in prometheus format. You need to configure prometheus to scrape http://localhost:3030/metrics on the relay.

Responses

Response Schema: text/plain
string <Prometheus metrics>

Request samples 

curl http://localhost:3030/metrics

Get relay information

Get information about the relay service

Responses

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

Result of the request

action
string
Value: "getSystemInfo"

The id of the action

object

Information about the service

Request samples 

curl http://localhost:3030/rudder/relay-api/1/system/info

Response samples

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

Reload relay service

Reload relay configuration and data files

Responses

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

Result of the request

action
required
string
Value: "getSystemInfo"

The id of the action

Request samples 

curl --request POST http://localhost:3030/rudder/relay-api/1/system/reload

Response samples

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

Get relay status

Get information about current relay service status

Responses

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

Result of the request

action
string
Value: "getStatus"

The id of the action

object

Status of the service

Request samples 

curl http://localhost:3030/rudder/relay-api/1/system/status

Response samples

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

Policies

Policies distributed by the relay

Download policies

Downloads an archive containing the policies to apply to the given node

path Parameters
nodeId
required
string <uuid>
Example: 4ac35ef0-582d-468d-8c95-cd3f2ee333f9

Id of the target node

Responses

Response Schema: application/zip
string <binary>

Request samples 

curl --output rudder.zip --cert "C:\...\etc\ssl\localhost.cert:Rudder-dsc passphrase" --key "C:\...\etc\ssl\localhost.priv" https://rudder.example.com/policies/3c0781e1-b59f-4b7e-a85b-819297dfce1d/rules/dsc/rudder.zip

Shared folder

Distribute file from the shared folder

Get the state a file from the shared folder

Get the state of a given file from the the shared folder of the policy server, typically to check if it needs to be updated. Note that contrary to what you could expect, the Content-Length and Content-Type headers will not match what you would get with a GET call on the same file.

path Parameters
path
required
string <path>
Example: myapplication/configuration.ini

Path of the file to download (relative to the shared-folder directory, /var/rudder/configuration-repository/shared-files)

query Parameters
hash
string <hexadecimal>
Example: hash=8ceb4b9ee5adedde47b31e975c1d90c73ad27b6b165a1dcd80c7c545eb65b903

Hash of the target file (hexadecimal string)

hash_type
string
Default: "sha256"
Enum: "sha256" "sha512"

Hash algorithm to use

Responses

Download a file from the shared folder

Downloads a given file from the the shared folder of the policy server

path Parameters
path
required
string <path>
Example: myapplication/configuration.ini

Path of the file to download (relative to the shared-folder directory, /var/rudder/configuration-repository/shared-files)

Responses

Response Schema: application/binary
string <binary>

Request samples 

curl --head --cert "C:\...\etc\ssl\localhost.cert:Rudder-dsc passphrase" --key "C:\...\etc\ssl\localhost.priv" 'https://rudder.example.com/rudder/relay-api/shared-folder/myapplication/myfile.conf?hash_type=sha256&hash=181210f8f9c779c26da1d9b2075bde0127302ee0e3fca38c9a83f5b1dd8e5d3b'

Shared files

Share files between nodes

Get the state a file in the shared files

Get the state of a given file from the the shared files of the policy server, typically to check if it needs to be sent. Note that contrary to what you could expect, the Content-Length and Content-Type headers will not match what you would get with a GET call on the same file.

path Parameters
sourceNodeId
required
string <uuid>
Example: 306136b2-69bb-40bc-928a-8e4eb5804bff

Id of the source node

targetNodeId
required
string <uuid>
Example: 4ac35ef0-582d-468d-8c95-cd3f2ee333f9

Id of the target node

fileId
required
string <id>
Example: my_file

Id of the file

query Parameters
hash
required
string <hexadecimal>
Example: hash=8ceb4b9ee5adedde47b31e975c1d90c73ad27b6b165a1dcd80c7c545eb65b903

Hash of the target file (hexadecimal string)

Responses

Request samples 

curl --head https://rudder.example.com/rudder/relay-api/shared-files/c745a140-40bc-4b86-b6dc-084488fc906b/37817c4d-fbf7-4850-a985-50021f4e8f41/file?hash=c22a3fb1e9de4bfa697ba258f60f14339b72c3faeb043cb75379b9ebcb2717c3

Upload a shared file

Shares a file, along with metadata and a ttl. The request body is a the concatenation of the metadata (containing the signature) with the file content, separated by an empty line. The receiving relay will either directly share it if the target node is a sub node, or forward the request to the appropriate relay (sub relay or upstream depending if it is under the current relay or not).

path Parameters
sourceNodeId
required
string <uuid>
Example: 306136b2-69bb-40bc-928a-8e4eb5804bff

Id of the source node

targetNodeId
required
string <uuid>
Example: 4ac35ef0-582d-468d-8c95-cd3f2ee333f9

Id of the target node

fileId
required
string <id>
Example: my_file

Id of the file

query Parameters
ttl
required
string <duration>
Example: ttl=1d

TTL of the file, can be a number of seconds or a duration (in the 1d 2h 3m 4s, 1d, 1 day, 3 hours, etc.) form

Request Body schema:
required

The file to share with its metadata

header
required
any
Value: "rudder-signature-v1"

Version of the metadata

algorithm
required
any
Enum: "sha256" "sha512"

Hash algorithm used in signature

digest
required
any

Signature of the uploaded file

hash_value
required
any

Hash of the file (using the given algorithm)

short_pubkey
required
any

Public key of the node (PEM without begin and end markers)

hostname
required
any

Hostname of source node

keydate
required
any

Formatted date, yyyy-mm-dd HH:mm:ss.ms +XXXX where XXXX stands for the four timezone digits, according to RFC 822.

keyid
required
any

Public key identifier (last 4 bytes of the modulus)

Responses

Remote run

Trigger agents runs

Trigger agent run on all the remote nodes

Trigger the agent on all of the managed nodes (if port 5309 is open to the node). WARNING: When running the agent, the /tmp folder may not be the global one but a private one, specific to the relay service. You should not rely on /tmp content in your policies but use /var/rudder/tmp instead.

Request Body schema: application/x-www-form-urlencoded
asynchronous
boolean
Default: false

Return early or wait for the end of the agent run

keep_output
boolean
Default: false

Forward agent output

conditions
string <comma-separated conditions>
Default: ""

Conditions passed as parameter to make it available during agent run, separated by a comma, each condition must match ^[a-zA-Z0-9][a-zA-Z0-9_]*$

classes
string

Deprecated alias for conditions

nodes
string <comma separated node ids>

Nodes to trigger run on, used only when calling /nodes

Responses

Response Schema: text/plain
string

Request samples 

curl --request POST https://rudder.example.com/rudder/relay-api/remote-run/all --data keep_output=true

Trigger agent run on a list of remote nodes

Trigger the agent on a list of managed nodes (if port 5309 is open to the node). WARNING: When running the agent, the /tmp folder may not be the global one but a private one, specific to the relay service. You should not rely on /tmp content in your policies but use /var/rudder/tmp instead.

Request Body schema: application/x-www-form-urlencoded
asynchronous
boolean
Default: false

Return early or wait for the end of the agent run

keep_output
boolean
Default: false

Forward agent output

conditions
string <comma-separated conditions>
Default: ""

Conditions passed as parameter to make it available during agent run, separated by a comma, each condition must match ^[a-zA-Z0-9][a-zA-Z0-9_]*$

classes
string

Deprecated alias for conditions

nodes
string <comma separated node ids>

Nodes to trigger run on, used only when calling /nodes

Responses

Response Schema: text/plain
string

Request samples 

curl --request POST https://rudder.example.com/rudder/relay-api/remote-run/nodes --data keep_output=true

Trigger agent run on a remote node

Trigger the agent on a managed node (if port 5309 is open to the node). WARNING: When running the agent, the /tmp folder may not be the global one but a private one, specific to the relay service. You should not rely on /tmp content in your policies but use /var/rudder/tmp instead.

path Parameters
nodeId
required
string <uuid>
Example: 4ac35ef0-582d-468d-8c95-cd3f2ee333f9

Id of the target node

Request Body schema: application/x-www-form-urlencoded
asynchronous
boolean
Default: false

Return early or wait for the end of the agent run

keep_output
boolean
Default: false

Forward agent output

conditions
string <comma-separated conditions>
Default: ""

Conditions passed as parameter to make it available during agent run, separated by a comma, each condition must match ^[a-zA-Z0-9][a-zA-Z0-9_]*$

classes
string

Deprecated alias for conditions

nodes
string <comma separated node ids>

Nodes to trigger run on, used only when calling /nodes

Responses

Response Schema: text/plain
string

Request samples 

curl --request POST https://rudder.example.com/rudder/relay-api/remote-run/nodes/2fc7a3a2-4050-4209-afe9-1c5ebc9ce2c8 --data keep_output=true