API: Semantic Model

Models, tables, fields, relationships, hierarchies, RLS policies, and SquareX measures. All endpoints require authentication unless noted. 48 endpoints.

`GET /api/models`

List semantic models

Query parameters

Name	Type	Required
`limit`	integer	no
`offset`	integer	no
`search`	string	no
`sort`	`"recent"` \| `"name"` \| `"tables"`	no

Responses: 200 · 400 · 401

`POST /api/models`

Create a new semantic model

Request body (JSON)

Field	Type	Required
`name`	string	yes
`description`	string	no
`sourceId`	string	yes

Responses: 201 · 400 · 401 · 409

`GET /api/models/{id}`

Get semantic model by ID

Path parameters

Name	Type	Required	Description
`id`	string	yes

Responses: 200 · 400 · 401 · 404

`PUT /api/models/{id}`

Update a semantic model

Path parameters

Name	Type	Required	Description
`id`	string	yes

Request body (JSON)

Field	Type	Required
`name`	string	no
`description`	string	no
`isCertified`	boolean	no
`certifiedBy`	string	no

Responses: 200 · 400 · 401 · 404

`DELETE /api/models/{id}`

Delete a semantic model

Path parameters

Name	Type	Required	Description
`id`	string	yes

Responses: 204 — No content · 401 · 404

`POST /api/models/{id}/publish`

Publish a model version (snapshot current state)

Path parameters

Name	Type	Required	Description
`id`	string	yes

Request body (JSON)

Field	Type	Required	Description
`override`	boolean	no
`overrideReason`	string	no

Responses: 200 · 400 · 401 · 404

`POST /api/models/{id}/suggest-relationships`

Generate AI relationship suggestions for a model

Path parameters

Name	Type	Required	Description
`id`	string	yes

Responses: 200

`GET /api/models/{id}/versions`

List model versions

Path parameters

Name	Type	Required	Description
`id`	string	yes

Responses: 200

`POST /api/models/{id}/versions/{version}/restore`

Restore the model definition from a version snapshot

Path parameters

Name	Type	Required	Description
`id`	string	yes
`version`	integer	yes

Responses: 200 · 400 · 401 · 404

`POST /api/models/{modelId}/ai-detect`

AI auto-detect relationships between tables

Path parameters

Name	Type	Required	Description
`modelId`	string	yes

Responses: 200 · 400 · 401 · 404

`GET /api/models/{modelId}/fields`

List all fields of a model (all tables, hidden excluded)

Path parameters

Name	Type	Required	Description
`modelId`	string	yes

Responses: 200

`GET /api/models/{modelId}/hierarchies`

List hierarchies in a model

Path parameters

Name	Type	Required	Description
`modelId`	string	yes

Responses: 200 · 400 · 401

`POST /api/models/{modelId}/hierarchies`

Create a drill-down hierarchy

Path parameters

Name	Type	Required	Description
`modelId`	string	yes

Request body (JSON)

Field	Type	Required
`name`	string	yes
`tableId`	string	no
`levels`	array of object	yes

Responses: 201 · 400 · 401 · 409

`PUT /api/models/{modelId}/hierarchies/{hierId}`

Update a hierarchy

Path parameters

Name	Type	Required	Description
`modelId`	string	yes
`hierId`	string	yes

Request body (JSON)

Field	Type	Required
`name`	string	no
`tableId`	string	no
`levels`	array of object	no

Responses: 200 · 400 · 401 · 404

`DELETE /api/models/{modelId}/hierarchies/{hierId}`

Delete a hierarchy

Path parameters

Name	Type	Required	Description
`modelId`	string	yes
`hierId`	string	yes

Responses: 204 — No content · 401 · 404

`POST /api/models/{modelId}/import-tables`

Import tables from the data source into the model

Path parameters

Name	Type	Required	Description
`modelId`	string	yes

Request body (JSON)

Field	Type	Required	Description
`schema`	string	no	Filter by schema name
`tables`	array of string	no	Specific table names to import (imports all if omitted)

Responses: 200

`GET /api/models/{modelId}/measures`

List SquareX measures on a model

Path parameters

Name	Type	Required	Description
`modelId`	string	yes

Responses: 200 · 400 · 401

`POST /api/models/{modelId}/measures`

Create a SquareX measure (validated at save)

Path parameters

Name	Type	Required	Description
`modelId`	string	yes

Request body (JSON)

Field	Type	Required
`name`	string	yes
`expression`	string	yes
`dataType`	`"number"` \| `"integer"` \| `"decimal"` \| `"string"` \| `"date"` \| `"boolean"`	no
`format`	object	no
`folder`	string	no
`description`	string	no
`isHidden`	boolean	no

Responses: 201 · 400 · 401 · 409

`GET /api/models/{modelId}/measures/{mid}`

Fetch a SquareX measure

Path parameters

Name	Type	Required	Description
`modelId`	string	yes
`mid`	string	yes

Responses: 200 · 400 · 401 · 404

`PUT /api/models/{modelId}/measures/{mid}`

Update a SquareX measure (revalidates; marks dependents stale)

Path parameters

Name	Type	Required	Description
`modelId`	string	yes
`mid`	string	yes

Request body (JSON)

Field	Type	Required
`name`	string	no
`expression`	string	no
`dataType`	`"number"` \| `"integer"` \| `"decimal"` \| `"string"` \| `"date"` \| `"boolean"`	no
`format`	object	no
`folder`	string	no
`description`	string	no
`isHidden`	boolean	no

Responses: 200 · 400 · 401 · 404

`DELETE /api/models/{modelId}/measures/{mid}`

Soft-delete a SquareX measure (409 while referenced)

Path parameters

Name	Type	Required	Description
`modelId`	string	yes
`mid`	string	yes

Responses: 204 — No content · 401 · 404

`POST /api/models/{modelId}/measures/{mid}/preview`

Compiled SQL preview of a SquareX measure for a dialect

Path parameters

Name	Type	Required	Description
`modelId`	string	yes
`mid`	string	yes

Request body (JSON)

Field	Type	Required	Description
`dialect`	string	no

Responses: 200 · 400 · 401 · 404

`POST /api/models/{modelId}/measures/copilot`

SquareX copilot: draft a measure from natural language, validated + self-repaired (AIX-18)

One cosmos call drafts an expression from the model’s real schema + glossary + canonical exemplars; the draft runs through the REAL analyzer and SQX0xx diagnostics are fed back for up to 2 repair rounds. ok:true is only returned for a GREEN expression — clients insert nothing else. 503 AI_NOT_CONFIGURED on keyless deploys.

Path parameters

Name	Type	Required	Description
`modelId`	string	yes

Request body (JSON)

Field	Type	Required
`prompt`	string	yes
`currentExpression`	string	no
`name`	string	no
`measureId`	string	no

Responses: 200 · 503

`POST /api/models/{modelId}/measures/validate`

Validate a SquareX expression (diagnostics, never a 4xx)

Path parameters

Name	Type	Required	Description
`modelId`	string	yes

Request body (JSON)

Field	Type	Required
`expression`	string	yes
`name`	string	no
`measureId`	string	no

Responses: 200 · 400 · 401 · 404

`GET /api/models/{modelId}/relationships`

List relationships in a model

Path parameters

Name	Type	Required	Description
`modelId`	string	yes

Responses: 200 · 400 · 401

`POST /api/models/{modelId}/relationships`

Create a relationship between model tables

Path parameters

Name	Type	Required	Description
`modelId`	string	yes

Request body (JSON)

Field	Type	Required
`fromTableId`	string	yes
`fromFieldId`	string	yes
`toTableId`	string	yes
`toFieldId`	string	yes
`joinType`	`"inner"` \| `"left"` \| `"right"` \| `"full"`	no
`cardinality`	`"1:1"` \| `"1:N"` \| `"N:M"`	no
`isActive`	boolean	no

Responses: 201 · 400 · 401 · 409

`PUT /api/models/{modelId}/relationships/{relId}`

Update a model relationship

Path parameters

Name	Type	Required	Description
`modelId`	string	yes
`relId`	string	yes

Request body (JSON)

Field	Type	Required
`fromTableId`	string	no
`fromFieldId`	string	no
`toTableId`	string	no
`toFieldId`	string	no
`joinType`	`"inner"` \| `"left"` \| `"right"` \| `"full"`	no
`cardinality`	`"1:1"` \| `"1:N"` \| `"N:M"`	no
`isActive`	boolean	no
`aiDetected`	boolean	no

Responses: 200 · 400 · 401 · 404

`DELETE /api/models/{modelId}/relationships/{relId}`

Delete a model relationship

Path parameters

Name	Type	Required	Description
`modelId`	string	yes
`relId`	string	yes

Responses: 204 — No content · 401 · 404

`GET /api/models/{modelId}/rls`

List RLS policies for a model

Path parameters

Name	Type	Required	Description
`modelId`	string	yes

Responses: 200 · 400 · 401

`POST /api/models/{modelId}/rls`

Create a row-level security policy

Path parameters

Name	Type	Required	Description
`modelId`	string	yes

Request body (JSON)

Field	Type	Required
`name`	string	yes
`tableId`	string	yes
`filterExpression`	string	yes
`appliesTo`	array of object	yes

Responses: 201 · 400 · 401 · 409

`PUT /api/models/{modelId}/rls/{policyId}`

Update an RLS policy

Path parameters

Name	Type	Required	Description
`modelId`	string	yes
`policyId`	string	yes

Request body (JSON)

Field	Type	Required
`name`	string	no
`tableId`	string	no
`filterExpression`	string	no
`appliesTo`	array of object	no

Responses: 200 · 400 · 401 · 404

`DELETE /api/models/{modelId}/rls/{policyId}`

Delete an RLS policy

Path parameters

Name	Type	Required	Description
`modelId`	string	yes
`policyId`	string	yes

Responses: 204 — No content · 401 · 404

`GET /api/models/{modelId}/tables`

List tables in a model

Path parameters

Name	Type	Required	Description
`modelId`	string	yes

Query parameters

Name	Type	Required	Description
`includeFields`	boolean	no	Include fields for each table

Responses: 200 · 400 · 401

`POST /api/models/{modelId}/tables`

Add a table to the model

Path parameters

Name	Type	Required	Description
`modelId`	string	yes

Request body (JSON)

Field	Type	Required
`sourceSchema`	string	yes
`sourceTable`	string	yes
`alias`	string	yes
`description`	string	no

Responses: 201 · 400 · 401 · 409

`GET /api/models/{modelId}/tables/{tableId}`

Get a model table by ID

Path parameters

Name	Type	Required	Description
`modelId`	string	yes
`tableId`	string	yes

Responses: 200 · 400 · 401 · 404

`PUT /api/models/{modelId}/tables/{tableId}`

Update a model table

Path parameters

Name	Type	Required	Description
`modelId`	string	yes
`tableId`	string	yes

Request body (JSON)

Field	Type	Required
`sourceSchema`	string	no
`sourceTable`	string	no
`alias`	string	no
`description`	string	no

Responses: 200 · 400 · 401 · 404

`DELETE /api/models/{modelId}/tables/{tableId}`

Delete a model table

Path parameters

Name	Type	Required	Description
`modelId`	string	yes
`tableId`	string	yes

Responses: 204 — No content · 401 · 404

`GET /api/models/{modelId}/tables/{tableId}/fields`

List fields for a model table

Path parameters

Name	Type	Required	Description
`modelId`	string	yes
`tableId`	string	yes

Responses: 200 · 400 · 401

`POST /api/models/{modelId}/tables/{tableId}/fields`

Add a field to a model table

Path parameters

Name	Type	Required	Description
`modelId`	string	yes
`tableId`	string	yes

Request body (JSON)

Field	Type	Required
`name`	string	yes
`sourceColumn`	string	no
`fieldType`	`"dimension"` \| `"measure"` \| `"calculated"`	yes
`dataType`	`"string"` \| `"number"` \| `"integer"` \| `"decimal"` \| `"boolean"` \| `"date"` \| `"datetime"` \| `"time"` \| `"geo"`	yes
`aggregation`	`"sum"` \| `"count"` \| `"count_distinct"` \| `"avg"` \| `"min"` \| `"max"` \| `"none"`	no
`expression`	string	no
`format`	string	no
`description`	string	no
`isHidden`	boolean	no
`sortByField`	string	no
`semanticType`	string	no
`isMetric`	boolean	no

Responses: 201 · 400 · 401 · 409

`PUT /api/models/{modelId}/tables/{tableId}/fields/{fieldId}`

Update a model field

Path parameters

Name	Type	Required
`modelId`	string	yes
`tableId`	string	yes
`fieldId`	string	yes

Request body (JSON)

Field	Type	Required
`name`	string	no
`sourceColumn`	string	no
`fieldType`	`"dimension"` \| `"measure"` \| `"calculated"`	no
`dataType`	`"string"` \| `"number"` \| `"integer"` \| `"decimal"` \| `"boolean"` \| `"date"` \| `"datetime"` \| `"time"` \| `"geo"`	no
`aggregation`	`"sum"` \| `"count"` \| `"count_distinct"` \| `"avg"` \| `"min"` \| `"max"` \| `"none"`	no
`expression`	string	no
`format`	string	no
`description`	string	no
`isHidden`	boolean	no
`sortByField`	string	no
`semanticType`	string	no
`isMetric`	boolean	no
`ordinal`	integer	no
`sensitivityLabel`	string	no

Responses: 200 · 400 · 401 · 404

`DELETE /api/models/{modelId}/tables/{tableId}/fields/{fieldId}`

Delete a model field

Path parameters

Name	Type	Required
`modelId`	string	yes
`tableId`	string	yes
`fieldId`	string	yes

Responses: 204 — No content · 401 · 404

`GET /api/models/{modelId}/tables/{tableId}/transforms`

List transform steps for a table

Path parameters

Name	Type	Required	Description
`modelId`	string	yes
`tableId`	string	yes

Responses: 200

`POST /api/models/{modelId}/tables/{tableId}/transforms`

Add a transform step to a table

Path parameters

Name	Type	Required	Description
`modelId`	string	yes
`tableId`	string	yes

Request body (JSON)

Field	Type	Required
`type`	`"filter_rows"` \| `"remove_columns"` \| `"rename_column"` \| `"change_type"` \| `"add_column"` \| `"replace_values"` \| `"sort_rows"` \| `"top_n"` \| `"deduplicate"` \| `"group_aggregate"`	yes
`config`	object	yes
`label`	string	no

Responses: 200

`PUT /api/models/{modelId}/tables/{tableId}/transforms/{transformId}`

Update a transform step

Path parameters

Name	Type	Required
`modelId`	string	yes
`tableId`	string	yes
`transformId`	string	yes

Request body (JSON)

Field	Type	Required
`config`	object	no
`label`	string	no
`isEnabled`	boolean	no

Responses: 200

`DELETE /api/models/{modelId}/tables/{tableId}/transforms/{transformId}`

Delete a transform step

Path parameters

Name	Type	Required
`modelId`	string	yes
`tableId`	string	yes
`transformId`	string	yes

Responses: 200

`POST /api/models/{modelId}/tables/{tableId}/transforms/reorder`

Reorder transform steps

Path parameters

Name	Type	Required	Description
`modelId`	string	yes
`tableId`	string	yes

Request body (JSON)

Field	Type	Required	Description
`orderedIds`	array of string	yes

Responses: 200

`POST /api/models/{modelId}/tables/resync`

Re-sync imported tables with the source’s latest discovered schema

Path parameters

Name	Type	Required	Description
`modelId`	string	yes

Responses: 200

`POST /api/models/{modelId}/validate-expression`

Validate a calculated-field expression

Path parameters

Name	Type	Required	Description
`modelId`	string	yes

Request body (JSON)

Field	Type	Required	Description
`expression`	string	yes
`tableId`	string	no	When set, referenced columns are checked against this table’s schema

Responses: 200 · 400 · 401 · 404