REST API Reference

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

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

Overview

Base URL: docx-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	docx-engine/api/v1/parameters	Return the raw parameter definitions declared in a DocX file

---

Endpoint Reference

GET docx-engine/api/v1/parameters

Summary: Returns the raw parameter definitions declared in the specified DocX 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
docx	string	Yes	Repository path to the DocX file (e.g. /User/admin/SalesReport.docx). URL-encode spaces and special characters.

Request body: none

Response — 200 OK:

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

[
  { "name": "Delivery Date", "type": "date",    "defaultValue": "2008-10-01" },
  { "name": "IsActive",      "type": "boolean", "defaultValue": "true" },
  { "name": "Quantity",      "type": "integer", "defaultValue": "10" },
  { "name": "TaxAmount",     "type": "number",  "defaultValue": "10" },
  { "name": "TotalAmount",   "type": "number",  "defaultValue": "150" }
]

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 docx query parameter is missing.

Example:

curl -H "Authentication: elx.token YOUR_TOKEN" \
     "https://your-server/docx-engine/api/v1/parameters?docx=/User/admin/Text%20Parameter.docx"

---

Parameter Types

The type field reflects exactly what the report author encoded in the DocX 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
textarea:<rows>	Multi-line text area; <rows> sets the visible row count (e.g. textarea:6)

---

Availability

Product	Minimum Version
Ambience	2026.1
Ambience (backport)	2024.0.12