Skip to main content
APIs to create, read, update, and delete semantic layer configurations for your datamarts. The semantic layer enriches your datamart with business-friendly metadata — descriptions, synonyms, column types, and feedback — to power AI chat mode and improve data discoverability.
The Semantic Layer API operates on existing datamarts. You must create a datamart first using the Datamart API before adding a semantic layer.

​
API Endpoints

​
Cloud Databrain Endpoint

https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer

​
Self-hosted Databrain Endpoint

<SELF_HOSTED_URL>/api/v2/data-app/datamarts/semantic-layer
The same routes are also mounted at /api/v2/dataApp/... (camelCase) if your client or proxy uses that prefix.

​
Authentication

All semantic layer endpoints require a service token (not a data app API token). Data app tokens will be rejected with a 403 AUTHENTICATION_ERROR.
​
Authorization
string
required
Bearer token for API authentication. Must be a service token.
Authorization: Bearer dbn_live_abc123...

​
Available Operations

Get Semantic Layer

Retrieve the semantic layer for a datamart including tables, columns, and completion score.

Create Semantic Layer

Add semantic metadata to a datamart that doesn’t have one yet.

Update Semantic Layer

Modify existing semantic layer metadata (descriptions, synonyms, feedback).

Delete Semantic Layer

Remove all semantic layer metadata from a datamart.

​
Key Concepts

​
Tables & Columns

Enrich your datamart tables and columns with:
  • Descriptions — natural-language explanations of what the data represents
  • Synonyms — alternative names users might search for (up to 10 per entity)
  • Column types — semantic classifications like String, Number, ENUM, Range, Identifier, etc.
  • Column type config — type-specific shape (e.g. value-to-description maps for ENUM / String types, { lowerLimit, upperLimit } for Range, strings for Expression / JSON)
  • Miscellaneous info — extra context for the AI to improve query generation

​
Feedback

A free-text field (up to 2000 characters) providing global context about the datamart to guide AI behavior.

​
Completion Score

A computed score (0–100) reflecting how thoroughly the semantic layer is filled out. Returned by the GET endpoint.