Semantic data models
Manage semantic data models (SDMs) — the semantic layer that lets an agent query your data in natural language. To attach an SDM to an agent, see Agents.
All paths are relative to the base URL and require an Authorization: Bearer YOUR_API_KEY header.
The SDM object
PublicSdm:
| Field | Type | Description |
|---|---|---|
| id | string | SDM ID. |
| name | string | SDM name. |
| description | string | What the model covers. |
| source | string | How it was created. |
| is_mutable | boolean | Whether it can be edited. |
| semantic_model | object | The full SDM body — same shape as the import/export payload. |
List SDMs
GET /semantic-data-models
Returns a PaginatedResponse of SDMs.
Get an SDM
GET /semantic-data-models/{semantic_data_model_id}
Returns a single PublicSdm.
Create an SDM
POST /semantic-data-models
Creates an SDM from a model body.
Body
| Field | Type | Required | Description |
|---|---|---|---|
| semantic_model | object | Yes | The semantic data model — must define at least one of tables or schemas. |
| thread_id | string | No | Thread to associate for post-create messaging. |
| version_id | string | No | Agent version ID, for version-scoped name uniqueness. |
The semantic_model body can't be empty — it has to declare non-empty tables or schemas. Returns the created PublicSdm.
Replace an SDM
PUT /semantic-data-models/{semantic_data_model_id}
Replaces an SDM's contents. Takes the same body as create. Returns the updated PublicSdm.
Delete an SDM
DELETE /semantic-data-models/{semantic_data_model_id}
Returns 204 No Content.
Scaffold from tables
POST /semantic-data-models/scaffold-from-tables
Inspects physical tables in a data connection and persists a draft SDM generated from them — a fast way to bootstrap a model instead of authoring it by hand.
Body
| Field | Type | Required | Description |
|---|---|---|---|
| data_connection_id | string | Yes | Connection to inspect (from Data connections). |
| tables | array | Yes | Physical table names to scaffold from (non-empty). |
| name | string | Yes | Name for the resulting SDM (unique within the account). |
| description | string | No | Optional description. |
Returns the persisted PublicSdm.
Scaffolding runs an inspection pipeline against an external data connection, so it's gated by a server-side flag and may be disabled on some deployments.
Import & export
Import
POST /semantic-data-models/import
Imports an SDM from the portable YAML/dict format. Data connections referenced by name are resolved against existing connections; Snowflake semantic-view SDMs are re-fetched from the live view.
Body
| Field | Type | Required | Description |
|---|---|---|---|
| semantic_model | object | string | Yes | The model with data_connection_name (dict or YAML string). |
| thread_id | string | No | Thread for file-reference resolution and post-create messaging. |
| agent_id | string | No | Agent ID for a deduplication check. |
Response — ImportSemanticDataModel
{
"semantic_data_model_id": "string",
"resolved_data_connections": { "name": "id" },
"is_duplicate": false,
"warnings": []
}Export
GET /semantic-data-models/{semantic_data_model_id}/export
Returns the SDM in the portable format.
Response — ExportSdmResponse
{ "content": "…serialised SDM…", "filename": "model.yaml", "format": "yaml" }