Update Semantic Layer

curl --request PUT \
  --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": "Updated: Customer purchase orders with status tracking",
        "columns": [
          {
            "name": "status",
            "description": "Order lifecycle status",
            "synonyms": ["order status", "state", "order state"]
          }
        ]
      }
    ],
    "feedback": "Updated context: All amounts in USD. Fiscal year starts April 1."
  }'

{
  "id": "sales-analytics"
}

curl --request PUT \
  --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": "Updated: Customer purchase orders with status tracking",
        "columns": [
          {
            "name": "status",
            "description": "Order lifecycle status",
            "synonyms": ["order status", "state", "order state"]
          }
        ]
      }
    ],
    "feedback": "Updated context: All amounts in USD. Fiscal year starts April 1."
  }'

{
  "id": "sales-analytics"
}

curl --request PUT \
  --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": "Updated: Customer purchase orders with status tracking",
        "columns": [
          {
            "name": "status",
            "description": "Order lifecycle status",
            "synonyms": ["order status", "state", "order state"]
          }
        ]
      }
    ],
    "feedback": "Updated context: All amounts in USD. Fiscal year starts April 1."
  }'

{
  "id": "sales-analytics"
}

PUT

api

data-app

datamarts

semantic-layer

curl --request PUT \
  --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": "Updated: Customer purchase orders with status tracking",
        "columns": [
          {
            "name": "status",
            "description": "Order lifecycle status",
            "synonyms": ["order status", "state", "order state"]
          }
        ]
      }
    ],
    "feedback": "Updated context: All amounts in USD. Fiscal year starts April 1."
  }'

{
  "id": "sales-analytics"
}

Modify the semantic layer metadata for an existing datamart. You can update table descriptions, column metadata, and feedback in a single request. Only the fields you include are updated — omitted tables and columns retain their existing values.

The datamart must already have a semantic layer. If no semantic data exists, this endpoint returns 404 SEMANTIC_LAYER_NOT_FOUND. Use POST to create a semantic layer first.

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 update. Must match exactly (case-sensitive).

tables

array

Array of table objects with updated semantic metadata. Only tables and columns included in the request are modified — others remain unchanged.

tables.name

string

required

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

tables.description

string

Updated description for the table. Maximum 500 characters.

tables.synonyms

string[]

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

tables.miscellaneousInfo

string

Updated additional context. Maximum 1000 characters.

tables.columns

array

Array of column objects to update. Only listed columns are modified.

tables.columns.name

string

required

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

tables.columns.description

string

Updated description. Maximum 500 characters.

tables.columns.synonyms

string[]

Updated synonyms. Maximum 10 synonyms, each up to 100 characters.

tables.columns.miscellaneousInfo

string

Updated additional context. Maximum 1000 characters.

tables.columns.columnType

string

Updated semantic column type. Must be one of: String, Long String, String (Custom), ENUM, Mapper, Range, Expression, Identifier, Number, JSON. Must be compatible with the column’s underlying datatype.

tables.columns.columnTypeConfig

object | string | null

Updated configuration for the column type. Same shapes as create: object map for String / String (Custom) / ENUM / Mapper; { lowerLimit, upperLimit } (numbers) for Range; string for Expression and JSON; null or omit for Identifier, Number, and Long String.

tables.columns.isIdentifier

boolean

Updated identifier flag.

tables.columns.isNotIndexed

boolean

Updated indexing exclusion flag.

feedback

string

Updated global feedback text. Maximum 2000 characters. When provided, replaces the existing feedback.

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 updated datamart (same as the input datamartName).

Examples

HTTP Status Code Summary

Status Code	Description
`200`	OK — Semantic layer updated 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
`404`	Not Found — No semantic layer exists for 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
`DUPLICATE_SYNONYM`	400	Duplicate synonyms detected (case-insensitive)
`SEMANTIC_LAYER_NOT_FOUND`	404	No semantic layer exists — use POST to create first
`AUTHENTICATION_ERROR`	403	Data app token used instead of service token
`INTERNAL_SERVER_ERROR`	500	Server error

Quick Start Guide

Get current semantic layer

Retrieve the existing semantic layer before making changes:

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

Save this response in case you need to rollback your changes.

Prepare your update

Determine what you want to update:

Tables/Columns: Include only the tables and columns you want to change
Feedback: Provide the new text (replaces existing)

Unlike the datamart update API, the semantic layer update is additive for tables and columns — only the ones you include are modified.

Update the semantic layer

curl --request PUT \
  --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", "feedback": "Updated context." }'

Verify the update

Retrieve the semantic layer again to confirm changes and check the updated completion score.

Next Steps

Get Semantic Layer

Retrieve and verify your changes

Create Semantic Layer

Create a semantic layer for a new datamart

Delete Semantic Layer

Remove semantic layer metadata entirely

Semantic Layer Guide

Configure the semantic layer in the Databrain UI

Create Semantic Layer

Delete Semantic Layer

​Authentication

​Headers

​Request Body

​Response

​Examples

​HTTP Status Code Summary

​Possible Errors

​Quick Start Guide

​Next Steps

Get Semantic Layer

Create 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