Create Semantic Layer

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "datamartName": "sales-analytics",
    "tables": [
      {
        "name": "orders",
        "description": "Customer purchase orders",
        "synonyms": ["purchases", "transactions"],
        "columns": [
          {
            "name": "order_id",
            "description": "Unique order identifier",
            "columnType": "Identifier",
            "isIdentifier": true
          },
          {
            "name": "status",
            "description": "Current order status",
            "synonyms": ["order status", "state"],
            "columnType": "ENUM"
          },
          {
            "name": "amount",
            "description": "Total order amount in USD",
            "columnType": "Number"
          }
        ]
      }
    ],
    "feedback": "This datamart covers e-commerce sales data. All amounts are in USD."
  }'

{
  "id": "sales-analytics"
}

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "datamartName": "sales-analytics",
    "tables": [
      {
        "name": "orders",
        "description": "Customer purchase orders",
        "synonyms": ["purchases", "transactions"],
        "columns": [
          {
            "name": "order_id",
            "description": "Unique order identifier",
            "columnType": "Identifier",
            "isIdentifier": true
          },
          {
            "name": "status",
            "description": "Current order status",
            "synonyms": ["order status", "state"],
            "columnType": "ENUM"
          },
          {
            "name": "amount",
            "description": "Total order amount in USD",
            "columnType": "Number"
          }
        ]
      }
    ],
    "feedback": "This datamart covers e-commerce sales data. All amounts are in USD."
  }'

{
  "id": "sales-analytics"
}

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "datamartName": "sales-analytics",
    "tables": [
      {
        "name": "orders",
        "description": "Customer purchase orders",
        "synonyms": ["purchases", "transactions"],
        "columns": [
          {
            "name": "order_id",
            "description": "Unique order identifier",
            "columnType": "Identifier",
            "isIdentifier": true
          },
          {
            "name": "status",
            "description": "Current order status",
            "synonyms": ["order status", "state"],
            "columnType": "ENUM"
          },
          {
            "name": "amount",
            "description": "Total order amount in USD",
            "columnType": "Number"
          }
        ]
      }
    ],
    "feedback": "This datamart covers e-commerce sales data. All amounts are in USD."
  }'

{
  "id": "sales-analytics"
}

POST

api

data-app

datamarts

semantic-layer

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "datamartName": "sales-analytics",
    "tables": [
      {
        "name": "orders",
        "description": "Customer purchase orders",
        "synonyms": ["purchases", "transactions"],
        "columns": [
          {
            "name": "order_id",
            "description": "Unique order identifier",
            "columnType": "Identifier",
            "isIdentifier": true
          },
          {
            "name": "status",
            "description": "Current order status",
            "synonyms": ["order status", "state"],
            "columnType": "ENUM"
          },
          {
            "name": "amount",
            "description": "Total order amount in USD",
            "columnType": "Number"
          }
        ]
      }
    ],
    "feedback": "This datamart covers e-commerce sales data. All amounts are in USD."
  }'

{
  "id": "sales-analytics"
}

Add semantic metadata to a datamart that doesn’t have a semantic layer yet. This includes table and column descriptions, synonyms, column type classifications, and global feedback for AI context.

This endpoint will reject the request with 409 SEMANTIC_LAYER_ALREADY_EXISTS if the datamart already has semantic data. Use PUT to modify an existing semantic layer.

At least one of tables or feedback must be provided in the request body.

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...

Content-Type

string

required

Must be set to application/json for all requests.

Content-Type: application/json

Request Body

datamartName

string

required

Name of the existing datamart to create a semantic layer for. Must match exactly (case-sensitive).

Show Finding datamart names

Use the List Datamarts API to get all datamart names
Names are case-sensitive and must match exactly
The datamart must not already have semantic data

tables

array

Array of table objects with semantic metadata. Each table must reference a table that exists in the datamart.

Show Validation rules

Table name must match an existing table in the datamart
Column name (when provided) must match an existing column in the respective table
Descriptions are limited to 500 characters
Synonyms are limited to 10 per entity, 100 characters each
Synonyms must be unique (case-insensitive)

tables.name

string

required

Table name from the datamart. Must match an existing table.

tables.schemaName

string

Optional schema name for the table.

tables.description

string

Human-readable description of the table. Maximum 500 characters.

tables.synonyms

string[]

Alternative names for the table. Maximum 10 synonyms, each up to 100 characters. Must be unique (case-insensitive).

tables.miscellaneousInfo

string

Additional context for AI query generation. Maximum 1000 characters.

tables.columns

array

Array of column objects with semantic metadata.

tables.columns.name

string

required

Column name from the table. Must match an existing column.

tables.columns.description

string

Human-readable description of the column. Maximum 500 characters.

tables.columns.synonyms

string[]

Alternative names for the column. Maximum 10 synonyms, each up to 100 characters. Must be unique (case-insensitive).

tables.columns.miscellaneousInfo

string

Additional context for AI query generation. Maximum 1000 characters.

tables.columns.columnType

string

Semantic column type classification. Must be one of: String, Long String, String (Custom), ENUM, Mapper, Range, Expression, Identifier, Number, JSON.

Show Column type compatibility

The column type must be compatible with the column’s underlying SQL datatype. For example, Number cannot be assigned to a varchar column.

tables.columns.columnTypeConfig

object | string | null

Additional configuration for the column type. Must match the shape expected for columnType:

String, String (Custom), ENUM, Mapper: plain object mapping values to descriptions (e.g. { "pending": "Not shipped", "shipped": "Sent" })
Range: { "lowerLimit": number, "upperLimit": number } (both must be numbers)
Expression: string template
JSON: string (sample JSON)
Identifier, Number, Long String: omit or use null (non-null config is rejected)

Show Config validation

Invalid configs return 400 INVALID_COLUMN_TYPE_CONFIG with a message describing the required shape.

tables.columns.isIdentifier

boolean

Mark this column as an identifier (e.g., primary key, foreign key). Defaults to false.

tables.columns.isNotIndexed

boolean

Exclude this column from AI indexing. Defaults to false.

feedback

string

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

Show Feedback usage

Helps guide AI-generated SQL queries
Example: “All monetary amounts are in USD. The fiscal year starts in April.”
Can be used alone (without tables)

Response

On success, the response body contains only the datamart name. There is no error field in the JSON body when the request succeeds.

string

The name of the datamart (same as the input datamartName) on success.

Examples

HTTP Status Code Summary

Status Code	Description
`200`	OK — Semantic layer created successfully
`400`	Bad Request — Validation failed (see error codes below)
`401`	Unauthorized — Invalid or missing API token
`403`	Forbidden — Data app token used instead of service token
`409`	Conflict — Semantic layer already exists on this datamart
`500`	Internal Server Error — Server error occurred

Possible Errors

Error Code	HTTP Status	Description
`INVALID_REQUEST_BODY`	400	Missing required fields or validation failure
`INVALID_DATAMART`	400	Datamart not found
`INVALID_TABLE`	400	Table name doesn’t exist in the datamart
`INVALID_COLUMN`	400	Column name doesn’t exist in the table
`INVALID_COLUMN_TYPE`	400	Column type incompatible with the column’s datatype
`INVALID_COLUMN_TYPE_CONFIG`	400	Column type config has wrong shape for the column type
`DUPLICATE_SYNONYM`	400	Duplicate synonyms detected (case-insensitive)
`SEMANTIC_LAYER_ALREADY_EXISTS`	409	Datamart already has semantic data — use PUT to update
`AUTHENTICATION_ERROR`	403	Data app token used instead of service token
`INTERNAL_SERVER_ERROR`	500	Server error

Quick Start Guide

Verify your datamart exists

Use the List Datamarts API to confirm the datamart exists and note its exact name.

Prepare your semantic metadata

Gather descriptions, synonyms, and column type classifications for your tables:

{
  "datamartName": "sales-analytics",
  "tables": [
    {
      "name": "orders",
      "description": "Customer purchase orders",
      "synonyms": ["purchases"],
      "columns": [
        { "name": "order_id", "description": "Unique identifier", "columnType": "Identifier" },
        { "name": "amount", "description": "Total in USD", "columnType": "Number" }
      ]
    }
  ],
  "feedback": "All monetary values are in USD."
}

Create the semantic layer

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{ ... }'

Verify with GET

Retrieve the semantic layer to confirm it was created and check the completion score:

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

Next Steps

Get Semantic Layer

Retrieve and inspect your semantic layer

Update Semantic Layer

Modify your semantic layer after creation

Delete Semantic Layer

Remove semantic layer metadata

Semantic Layer Guide

Configure the semantic layer in the Databrain UI

Get Semantic Layer

Update Semantic Layer

​Authentication

​Headers

​Request Body

​Response

​Examples

​HTTP Status Code Summary

​Possible Errors

​Quick Start Guide

​Next Steps

Get Semantic Layer

Update Semantic Layer

Delete Semantic Layer

Semantic Layer Guide

Authentication

Headers

Request Body

Response

Examples

HTTP Status Code Summary

Possible Errors

Quick Start Guide

Next Steps