REST API Reference

The RML Engine exposes a REST API for programmatic access to template metadata. External scripts, ETL pipelines, and integration tools can use these endpoints to inspect RML files without rendering them or navigating the Ambience UI.

Endpoints under rml-engine/api/v1 are official, maintained endpoints. Other rml-engine endpoints not under the api path may change between releases.

Overview

Base URL: rml-engine/api/v1

Content-Type: application/json

Access control: All endpoints access the repository on behalf of the authenticated user. Files the caller cannot read in the Repository module are equally inaccessible through the API.

---

Endpoints

Method	Path	Summary
GET	rml-engine/api/v1/parameters	Return the raw parameter definitions declared in an RML file

---

Endpoint Reference

GET rml-engine/api/v1/parameters

Summary: Returns the raw parameter definitions declared in the specified RML file as a JSON array. Each object contains the parameter name, its declared type, and its default value exactly as encoded in the template — without any HTML rendering.

This is the only way to retrieve structured parameter information programmatically. The get-parameters path used by the Ambience UI returns an HTML web form, not machine-readable data.

Query parameters:

Parameter	Type	Required	Description
rml	string	Yes	Repository path to the RML file (e.g. /User/admin/SalesReport.rml). URL-encode spaces and special characters.

Request body: none

Response — 200 OK:

A JSON array where each element represents one parameter declared in the RML file.

[
  { "name": "Date",      "type": "date",                  "defaultValue": "2005-01-05" },
  { "name": "Integer",   "type": "integer",               "defaultValue": "20" },
  { "name": "MyChoices", "type": "choice(Apple,Boy,Cat)", "defaultValue": "Boy" },
  { "name": "Number",    "type": "number",                "defaultValue": "23.5" },
  { "name": "Password",  "type": "password",              "defaultValue": "MyPassword" },
  { "name": "User",      "type": "",                      "defaultValue": "MyName" }
]

Returns an empty array [] when the file has no parameters.

Response fields:

Field	Type	Description
[].name	string	The parameter name as declared in the template.
[].type	string	The parameter type string. See Parameter Types for known values. Empty string when no type is declared.
[].defaultValue	string	The default value for the parameter. Empty string when no default is declared.

Error responses:

Status	Condition
400 Bad Request	The rml query parameter is missing.

Example:

curl -H "Authentication: elx.token YOUR_TOKEN" \
     "https://your-server/rml-engine/api/v1/parameters?rml=/User/admin/FruitSalesWithParam.rml"

---

Parameter Types

The type field reflects exactly what the report author encoded in the RML template using the ${name#type#defaultValue} parameter syntax. The engine does not validate or normalise type strings — a template with a custom or unrecognised type returns it as-is.

Type value	UI input rendered by the engine
(empty string)	Plain text field
date	Date picker (value format: YYYY-MM-DD)
integer	Integer number field
number	Decimal number field
password	Password field (masked)
boolean	True/false checkbox
choice(A,B,C)	Drop-down with the listed options

---

Availability

Product	Minimum Version
Ambience	2026.1
Ambience (backport)	2024.0.12