REST API
API: Blending
Define, inspect, execute, and remove governed cross-source blends. All endpoints require authentication unless noted. 8 endpoints.
GET /api/composite-models
Section titled “GET /api/composite-models”List cross-source blends
Responses: 200 · 400 · 401
POST /api/composite-models
Section titled “POST /api/composite-models”Define a cross-source blend
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | yes | |
description |
string | null | no | |
leftTableId |
string | yes | |
leftAlias |
string | yes | |
rightTableId |
string | yes | |
rightAlias |
string | yes | |
keys |
array of object | yes | |
joinType |
"inner" | "left" | "full" |
no | |
extraSides |
array of object | no |
Responses: 201 · 400 · 401 · 409
GET /api/composite-models/{id}
Section titled “GET /api/composite-models/{id}”Get a cross-source blend
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes |
Responses: 200 · 400 · 401 · 404
PUT /api/composite-models/{id}
Section titled “PUT /api/composite-models/{id}”Redefine a cross-source blend
Replaces the whole definition, validated as a new blend is (400 when refused). A change to how it joins, while cards on live dashboards run it, is refused with 409 BLEND_IN_USE unless confirmUsedBy is true.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes |
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | yes | |
description |
string | null | no | |
leftTableId |
string | yes | |
leftAlias |
string | yes | |
rightTableId |
string | yes | |
rightAlias |
string | yes | |
keys |
array of object | yes | |
joinType |
"inner" | "left" | "full" |
no | |
extraSides |
array of object | no | |
confirmUsedBy |
boolean | no | Save a change to how the blend joins (its sides, aliases, join types or keys) although cards on live dashboards run it. Without it such a change is refused with 409 BLEND_IN_USE, whose details.usedBy says which dashboards it changes (as GET /:id’s usedBy). A new name or description needs no confirmation. |
Responses: 200 · 400 · 401 · 404 · 409
DELETE /api/composite-models/{id}
Section titled “DELETE /api/composite-models/{id}”Delete a cross-source blend
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes |
Responses: 200 · 400 · 401 · 404
POST /api/composite-models/{id}/execute
Section titled “POST /api/composite-models/{id}/execute”Run a cross-source blend
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes |
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
leftColumns |
array of string | yes | |
rightColumns |
array of string | yes | |
leftFilters |
array of object | no | |
rightFilters |
array of object | no | |
sideColumns |
object | no | For a blend of more than two sources: selected columns of each further side, keyed by its alias. |
sideFilters |
object | no | For a blend of more than two sources: filters on each further side’s own columns, keyed by its alias. |
groupBy |
array of object | no | Group keys, each { side: left|right, column }. With groupBy or aggregates set, the result is the group keys then the aggregates, and leftColumns/rightColumns may name group keys only. |
aggregates |
array of object | no | Aggregates, each { side, column, fn: sum|avg|count|min|max|count_distinct }; the output column is named side-alias_fn_column, e.g. orders_sum_total. |
pushdown |
boolean | no | Pre-aggregate the right side in its own engine when that cannot change a total (default true). The response’s plan.aggregation says whether it was, or names the condition that refused it. |
Responses: 200 · 400 · 401 · 404
GET /api/composite-models/{id}/fields
Section titled “GET /api/composite-models/{id}/fields”List the fields each side of a blend can project
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes |
Responses: 200 · 400 · 401 · 404
GET /api/composite-models/{id}/plan
Section titled “GET /api/composite-models/{id}/plan”Preview what a blend will read, before running it
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes |
Responses: 200 · 400 · 401 · 404