eMondrian answers data queries over a REST API with JSON, next to XMLA. It is meant for systems that are not BI clients: backends, scripts, ETL jobs, low-code tools such as n8n or Retool, and services an AI agent writes for you. No SOAP, no XMLA library.
- Read-only. It runs queries; it doesn’t change schemas or write data back.
- No licence key. A DAX query still needs the DAX module, as everywhere.
- Same security as XMLA. The same sign-in methods, and the caller’s schema roles, row-level security included, on every query.
Available from Community 2026.11.20 (modules 0.0.0.112).
Endpoints
Base address: https://<your server>/api/v1.
| Request | Answer |
|---|---|
GET /api/v1 | API version and the server’s limits |
GET /api/v1/openapi.json | The OpenAPI 3 description |
GET /api/v1/catalogs | The catalogs, each with the cubes you may see |
GET /api/v1/catalogs/{catalog}/cubes/{cube} | Dimensions, hierarchies, levels and measures, as you see them. For names awkward in a path: GET /api/v1/cube?catalog=…&cube=… |
POST /api/v1/query | The result of an MDX or DAX query, as a table |
Sign in
Every sign-in method of XMLA works here. See Security.
| Method | How to send it |
|---|---|
| User name and password | HTTP Basic |
Personal access token (emk_…) | Authorization: Bearer emk_…, or as the password in Basic with its owner’s user name |
| OAuth access token | Authorization: Bearer <token> |
XML/A link (eml_…) | Only as the query parameter: …/api/v1/query?emondrian_token=eml_…. A replaced or revoked link stops working within 30 seconds |
Every request through the gateway is a line in its access log, with the user, the groups and the sign-in method. An XML/A link is masked there.
A service of your own inside the installation (on the same Docker network, like the built-in Dashboard) can instead call the server directly at http://eMondrian:8080/emondrian/api/v1/… with X-Forwarded-User (and X-Forwarded-Groups) and the gateway’s secret in X-Forwarded-Secret. Without the right secret the server refuses a request that names a user. Such calls don’t pass through the gateway, so its access log doesn’t show them.
Run a query
curl -u anna -H 'Content-Type: application/json' https://bi.example.com/api/v1/query -d '{
"catalog": "FoodMart",
"query": "SELECT {[Measures].[Unit Sales]} ON 0, NON EMPTY [Store].[Store State].Members ON 1 FROM [Sales]"
}'{
"language": "MDX",
"catalog": "FoodMart",
"format": "plain",
"columns": [
{ "name": "Store State", "uniqueName": "[Store].[Store State]", "kind": "member", "type": "string" },
{ "name": "Unit Sales", "uniqueName": "[Measures].[Unit Sales]", "kind": "measure", "type": "number" }
],
"rows": [
{ "Store State": "CA", "Unit Sales": 74748 },
{ "Store State": "OR", "Unit Sales": 67659 },
{ "Store State": "WA", "Unit Sales": 124366 }
],
"rowCount": 3,
"returnedRows": 3,
"truncated": false,
"elapsedMs": 9
}The request body is JSON (Content-Type: application/json):
| Field | Required | Meaning |
|---|---|---|
catalog | yes | Catalog name |
query | yes | MDX, or DAX: a query that starts with EVALUATE or DEFINE |
cube | DAX only, when the catalog has more than one cube | Cube name. MDX names its cube in FROM |
format | no | plain (default) or detailed |
maxRows | no | Rows to return. Above the server’s maximum, the request is refused |
timeoutSeconds | no | Time limit. Above the server’s maximum, the request is refused |
Any other field is refused with 400.
MDX and DAX results
MDX comes back flat: the members of the row axis become columns named after their level, and every position of the column axis becomes a value column. Queries with more than two axes are refused.
DAX comes back as the table the query defines, with its own column names. FoodMart has several cubes, so the request names one:
{ "catalog": "FoodMart", "cube": "Sales", "query": "EVALUATE SUMMARIZECOLUMNS(Store[Store State], \"Unit Sales\", [Unit Sales])" }"columns": [
{ "name": "Store[Store State]", "uniqueName": null, "kind": "column", "type": "string" },
{ "name": "[Unit Sales]", "uniqueName": null, "kind": "column", "type": "number" }
],
"rows": [
{ "Store[Store State]": "CA", "[Unit Sales]": 74748 },
{ "Store[Store State]": "OR", "[Unit Sales]": 67659 },
{ "Store[Store State]": "WA", "[Unit Sales]": 124366 }
]Detailed format
With "format": "detailed" members come with their unique names and values with their formatted text:
"rows": [
{
"Store State": { "caption": "OR", "uniqueName": "[Store].[USA].[OR]" },
"Unit Sales": { "value": 67659, "formatted": "67,659" }
}
]Only queries run. DRILLTHROUGH, DMV queries, writeback and transaction statements are refused.
Roles and row-level security
Every query runs as the user who signed in, with that user’s schema roles, as in Excel, Power BI and AI agents.
For example, a user whose role allows only Oregon sends the same MDX as above and gets one row:
"rows": [ { "Store State": "OR", "Unit Sales": 67659 } ],
"rowCount": 1In GET /api/v1/catalogs the same user sees every catalog, but in each only the cubes the roles allow.
Limits
GET /api/v1 shows the server’s limits. Each is a -D option in JAVA_TOOL_OPTIONS of the eMondrian service:
| Option | Default | Meaning |
|---|---|---|
emondrian.rest.defaultRows | 10,000 | Rows in an answer when the request doesn’t say |
emondrian.rest.maxRows | 100,000 | The most a request’s maxRows may ask for |
emondrian.rest.maxCells | 2,000,000 | Cells in an answer (rows Ă— value columns) |
emondrian.rest.maxTimeoutSeconds | 300 | Time limit, also the default |
emondrian.rest.maxBodyBytes | 1 MB | Request size |
emondrian.rest.enabled | true | false switches the API off |
rowCount is the number of rows in the result, returnedRows the number sent; truncated is true when some were left out.
Errors
Errors are JSON with the HTTP status:
{ "error": { "code": "UNAUTHORIZED", "message": "Authentication required" } }| Status | Code | When |
|---|---|---|
| 400 | BAD_REQUEST | The request is not valid |
| 401 | UNAUTHORIZED | No or wrong credentials |
| 403 | FORBIDDEN | Not allowed |
| 404 | NOT_FOUND | Unknown catalog or cube |
| 405 | METHOD_NOT_ALLOWED | Wrong HTTP method |
| 413, 422 | TOO_LARGE | Request or result too large |
| 415 | UNSUPPORTED_MEDIA_TYPE | The body is not JSON |
| 422 | UNSUPPORTED_QUERY | Writeback, DRILLTHROUGH or DMV |
| 422 | UNSUPPORTED_SHAPE | More than two axes, or too many cells |
| 422 | QUERY_ERROR | The engine refused the query; the message says why |
| 502 | DATABASE_ERROR | The database failed |
| 503 | QUERY_CANCELED | The query was canceled |
| 504 | QUERY_TIMEOUT | The time ran out |
| 500 | INTERNAL | Server error |
Failures inside the database or the server are not described to the caller; the server log has them. See Logs.
Web pages on other sites (CORS)
By default, no page on another web site may call the REST API or /xmla from a browser.
A token in a web page’s code can be read by anyone who opens the page. Call eMondrian from your server where you can. Sites that must call it from the browser are listed in auth/identity.yml:
cors:
allowed_origins: [https://app.example.com]then run auth/scripts/apply-config.sh. Each listed site gets its own origin in Access-Control-Allow-Origin, never * and never with cookies: its page sends a token in the Authorization header. CORS_ALLOW_ORIGIN in .env doesn’t apply to these paths.
See also
- Security: sign-in, tokens, roles
- AI agents (MCP): the same queries for AI agents
- XMLA