Skip to main content
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
/
v2
/
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:
  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...
​
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.
​
id
string
The name of the updated datamart (same as the input datamartName).

​
Examples

​
HTTP Status Code Summary

Status CodeDescription
200OK — Semantic layer updated successfully
400Bad Request — Validation failed (see error codes below)
401Unauthorized — Invalid or missing API token
403Forbidden — Data app token used instead of service token
404Not Found — No semantic layer exists for this datamart
500Internal Server Error — Server error occurred

​
Possible Errors

Error CodeHTTP StatusDescription
INVALID_REQUEST_BODY400Missing required fields or validation failure
INVALID_DATAMART400Datamart not found
INVALID_TABLE400Table name doesn’t exist in the datamart
INVALID_COLUMN400Column name doesn’t exist in the table
INVALID_COLUMN_TYPE400Column type incompatible with the column’s datatype
INVALID_COLUMN_TYPE_CONFIG400Column type config has wrong shape
DUPLICATE_SYNONYM400Duplicate synonyms detected (case-insensitive)
SEMANTIC_LAYER_NOT_FOUND404No semantic layer exists — use POST to create first
AUTHENTICATION_ERROR403Data app token used instead of service token
INTERNAL_SERVER_ERROR500Server error

​
Quick Start Guide

1

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

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

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." }'
4

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