Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.usedatabrain.com/llms.txt

Use this file to discover all available pages before exploring further.

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.