Skip to main content
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
/
v2
/
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:
  1. Go to your Databrain dashboard and open Settings.
  2. Navigate to Settings.
  3. Find the Service Tokens section.
  4. 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.

​
Response

​
data
object
The semantic layer data for the requested datamart.
​
error
null | object
Error object if the request failed, otherwise not present for successful requests.

​
Examples

​
HTTP Status Code Summary

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

​
Possible Errors

Error CodeHTTP StatusDescription
INVALID_DATAMART400datamartName is missing or datamart doesn’t exist
AUTHENTICATION_ERROR403Data app token used instead of service token
INTERNAL_SERVER_ERROR500Server 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