Get Semantic Layer

curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer?datamartName=sales-analytics' \
  --header 'Authorization: Bearer dbn_live_abc123...'

{
  "data": {
    "datamartName": "sales-analytics",
    "tables": [
      {
        "name": "orders",
        "schemaName": "public",
        "description": "Customer purchase orders",
        "synonyms": ["purchases", "transactions"],
        "miscellaneousInfo": null,
        "columns": [
          {
            "name": "order_id",
            "datatype": "integer",
            "description": "Unique order identifier",
            "synonyms": ["id", "order number"],
            "miscellaneousInfo": null,
            "columnType": "Identifier",
            "columnTypeConfig": null,
            "isIdentifier": true,
            "isNotIndexed": false
          },
          {
            "name": "status",
            "datatype": "varchar",
            "description": "Current order status",
            "synonyms": ["order status", "state"],
            "miscellaneousInfo": null,
            "columnType": "ENUM",
            "columnTypeConfig": null,
            "isIdentifier": false,
            "isNotIndexed": false
          },
          {
            "name": "amount",
            "datatype": "numeric",
            "description": "Total order amount in USD",
            "synonyms": ["total", "price"],
            "miscellaneousInfo": null,
            "columnType": "Number",
            "columnTypeConfig": null,
            "isIdentifier": false,
            "isNotIndexed": false
          }
        ]
      }
    ],
    "feedback": "This datamart covers e-commerce sales data. Amounts are in USD.",
    "completionScore": 75,
    "lastUpdated": "2026-03-15T10:30:00.000Z"
  }
}

curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer?datamartName=sales-analytics' \
  --header 'Authorization: Bearer dbn_live_abc123...'

{
  "data": {
    "datamartName": "sales-analytics",
    "tables": [
      {
        "name": "orders",
        "schemaName": "public",
        "description": "Customer purchase orders",
        "synonyms": ["purchases", "transactions"],
        "miscellaneousInfo": null,
        "columns": [
          {
            "name": "order_id",
            "datatype": "integer",
            "description": "Unique order identifier",
            "synonyms": ["id", "order number"],
            "miscellaneousInfo": null,
            "columnType": "Identifier",
            "columnTypeConfig": null,
            "isIdentifier": true,
            "isNotIndexed": false
          },
          {
            "name": "status",
            "datatype": "varchar",
            "description": "Current order status",
            "synonyms": ["order status", "state"],
            "miscellaneousInfo": null,
            "columnType": "ENUM",
            "columnTypeConfig": null,
            "isIdentifier": false,
            "isNotIndexed": false
          },
          {
            "name": "amount",
            "datatype": "numeric",
            "description": "Total order amount in USD",
            "synonyms": ["total", "price"],
            "miscellaneousInfo": null,
            "columnType": "Number",
            "columnTypeConfig": null,
            "isIdentifier": false,
            "isNotIndexed": false
          }
        ]
      }
    ],
    "feedback": "This datamart covers e-commerce sales data. Amounts are in USD.",
    "completionScore": 75,
    "lastUpdated": "2026-03-15T10:30:00.000Z"
  }
}

curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer?datamartName=sales-analytics' \
  --header 'Authorization: Bearer dbn_live_abc123...'

{
  "data": {
    "datamartName": "sales-analytics",
    "tables": [
      {
        "name": "orders",
        "schemaName": "public",
        "description": "Customer purchase orders",
        "synonyms": ["purchases", "transactions"],
        "miscellaneousInfo": null,
        "columns": [
          {
            "name": "order_id",
            "datatype": "integer",
            "description": "Unique order identifier",
            "synonyms": ["id", "order number"],
            "miscellaneousInfo": null,
            "columnType": "Identifier",
            "columnTypeConfig": null,
            "isIdentifier": true,
            "isNotIndexed": false
          },
          {
            "name": "status",
            "datatype": "varchar",
            "description": "Current order status",
            "synonyms": ["order status", "state"],
            "miscellaneousInfo": null,
            "columnType": "ENUM",
            "columnTypeConfig": null,
            "isIdentifier": false,
            "isNotIndexed": false
          },
          {
            "name": "amount",
            "datatype": "numeric",
            "description": "Total order amount in USD",
            "synonyms": ["total", "price"],
            "miscellaneousInfo": null,
            "columnType": "Number",
            "columnTypeConfig": null,
            "isIdentifier": false,
            "isNotIndexed": false
          }
        ]
      }
    ],
    "feedback": "This datamart covers e-commerce sales data. Amounts are in USD.",
    "completionScore": 75,
    "lastUpdated": "2026-03-15T10:30:00.000Z"
  }
}

GET

api

data-app

datamarts

semantic-layer

curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer?datamartName=sales-analytics' \
  --header 'Authorization: Bearer dbn_live_abc123...'

{
  "data": {
    "datamartName": "sales-analytics",
    "tables": [
      {
        "name": "orders",
        "schemaName": "public",
        "description": "Customer purchase orders",
        "synonyms": ["purchases", "transactions"],
        "miscellaneousInfo": null,
        "columns": [
          {
            "name": "order_id",
            "datatype": "integer",
            "description": "Unique order identifier",
            "synonyms": ["id", "order number"],
            "miscellaneousInfo": null,
            "columnType": "Identifier",
            "columnTypeConfig": null,
            "isIdentifier": true,
            "isNotIndexed": false
          },
          {
            "name": "status",
            "datatype": "varchar",
            "description": "Current order status",
            "synonyms": ["order status", "state"],
            "miscellaneousInfo": null,
            "columnType": "ENUM",
            "columnTypeConfig": null,
            "isIdentifier": false,
            "isNotIndexed": false
          },
          {
            "name": "amount",
            "datatype": "numeric",
            "description": "Total order amount in USD",
            "synonyms": ["total", "price"],
            "miscellaneousInfo": null,
            "columnType": "Number",
            "columnTypeConfig": null,
            "isIdentifier": false,
            "isNotIndexed": false
          }
        ]
      }
    ],
    "feedback": "This datamart covers e-commerce sales data. Amounts are in USD.",
    "completionScore": 75,
    "lastUpdated": "2026-03-15T10:30:00.000Z"
  }
}

Retrieve the full semantic layer for a given datamart. The response includes table and column metadata (descriptions, synonyms, column types), feedback text, a completion score, and the last-updated timestamp.

This endpoint returns data for datamarts that exist in your organization — even if no semantic layer has been configured yet. In that case, tables are returned with null/empty semantic fields.

Authentication

This endpoint requires a service token in the Authorization header. Data app API tokens are not permitted and will be rejected with a 403 error. To access your service token:

Go to your Databrain dashboard and open Settings.
Navigate to Settings.
Find the Service Tokens section.
Click the “Generate Token” button to generate a new service token if you don’t have one already.

Use this token as the Bearer value in your Authorization header.

Headers

Authorization

string

required

Bearer token for API authentication. Use your service token.

Authorization: Bearer dbn_live_abc123...

Query Parameters

datamartName

string

required

The name of the datamart whose semantic layer you want to retrieve. Must match an existing datamart in your organization.

Show Finding datamart names

Use the List Datamarts API to get all datamart names
Names are case-sensitive and must match exactly

Response

data

object

The semantic layer data for the requested datamart.

Show data properties

data.datamartName

string

Name of the datamart.

data.tables

array

Array of table objects with semantic metadata.

Show table properties

name

string

Table name from the datasource.

schemaName

string | null

Schema name, or null if not set.

description

string | null

Human-readable description of the table.

synonyms

string[]

Alternative names for the table. Empty array if none set.

miscellaneousInfo

string | null

Additional context for AI query generation.

columns

array

Array of column objects with semantic metadata.

Show column properties

name

string

Column name from the datasource.

datatype

string | null

The underlying SQL datatype of the column.

description

string | null

Human-readable description of the column.

synonyms

string[]

Alternative names for the column.

miscellaneousInfo

string | null

Additional context for AI query generation.

columnType

string | null

Semantic column type. One of: String, Long String, String (Custom), ENUM, Mapper, Range, Expression, Identifier, Number, JSON.

columnTypeConfig

object | string | null

Stored column-type configuration as saved via the API (object maps for ENUM-like types, { lowerLimit, upperLimit } for Range, strings for Expression/JSON, or null).

isIdentifier

boolean

Whether this column is marked as an identifier.

isNotIndexed

boolean

Whether this column is excluded from AI indexing.

data.feedback

string | null

Global feedback text providing context to the AI about this datamart.

data.completionScore

number

A score from 0 to 100 indicating how thoroughly the semantic layer is configured.

data.lastUpdated

string | null

ISO 8601 timestamp of the last semantic layer update, or null if never updated.

error

null | object

Error object if the request failed, otherwise not present for successful requests.

Examples

HTTP Status Code Summary

Status Code	Description
`200`	OK — Semantic layer retrieved successfully
`400`	Bad Request — Missing or invalid datamartName
`401`	Unauthorized — Invalid or missing API token
`403`	Forbidden — Data app token used instead of service token
`500`	Internal Server Error — Server error occurred

Possible Errors

Error Code	HTTP Status	Description
`INVALID_DATAMART`	400	datamartName is missing or datamart doesn’t exist
`AUTHENTICATION_ERROR`	403	Data app token used instead of service token
`INTERNAL_SERVER_ERROR`	500	Server error

Next Steps

Create Semantic Layer

Add semantic metadata to your datamart

Update Semantic Layer

Modify existing semantic layer metadata

Semantic Layer Guide

Learn how to configure the semantic layer in the UI

List Datamarts

Find datamart names in your organization

Semantic Layer API

Create Semantic Layer

​Authentication

​Headers

​Query Parameters

​Response

​Examples

​HTTP Status Code Summary

​Possible Errors

​Next Steps

Create Semantic Layer

Update Semantic Layer

Semantic Layer Guide

List Datamarts

Authentication

Headers

Query Parameters

Response

Examples

HTTP Status Code Summary

Possible Errors

Next Steps