> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedatabrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Semantic Layer API

APIs to create, read, update, and delete semantic layer configurations for your datamarts. The semantic layer enriches your datamart with business-friendly metadata — descriptions, synonyms, column types, and feedback — to power AI chat mode and improve data discoverability.

<Note>
  The Semantic Layer API operates on **existing datamarts**. You must create a datamart first using the [Datamart API](/developer-docs/helpers/api-reference/create-datamart) before adding a semantic layer.
</Note>

## API Endpoints

### Cloud Databrain Endpoint

```bash theme={"dark"}
https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer
```

### Self-hosted Databrain Endpoint

```bash theme={"dark"}
<SELF_HOSTED_URL>/api/v2/data-app/datamarts/semantic-layer
```

The same routes are also mounted at `/api/v2/dataApp/...` (camelCase) if your client or proxy uses that prefix.

## Authentication

All semantic layer endpoints require a **service token** (not a data app API token). Data app tokens will be rejected with a `403 AUTHENTICATION_ERROR`.

<ParamField header="Authorization" type="string" required>
  Bearer token for API authentication. Must be a service token.

  ```
  Authorization: Bearer dbn_live_abc123...
  ```
</ParamField>

## Available Operations

<CardGroup cols={2}>
  <Card title="Get Semantic Layer" icon="eye" href="/developer-docs/helpers/api-reference/get-semantic-layer">
    Retrieve the semantic layer for a datamart including tables, columns, and completion score.
  </Card>

  <Card title="Create Semantic Layer" icon="plus" href="/developer-docs/helpers/api-reference/create-semantic-layer">
    Add semantic metadata to a datamart that doesn't have one yet.
  </Card>

  <Card title="Update Semantic Layer" icon="pen" href="/developer-docs/helpers/api-reference/update-semantic-layer">
    Modify existing semantic layer metadata (descriptions, synonyms, feedback).
  </Card>

  <Card title="Delete Semantic Layer" icon="trash" href="/developer-docs/helpers/api-reference/delete-semantic-layer">
    Remove all semantic layer metadata from a datamart.
  </Card>
</CardGroup>

## Key Concepts

### Tables & Columns

Enrich your datamart tables and columns with:

* **Descriptions** — natural-language explanations of what the data represents
* **Synonyms** — alternative names users might search for (up to 10 per entity)
* **Column types** — semantic classifications like `String`, `Number`, `ENUM`, `Range`, `Identifier`, etc.
* **Column type config** — type-specific shape (e.g. value-to-description maps for `ENUM` / `String` types, `{ lowerLimit, upperLimit }` for `Range`, strings for `Expression` / `JSON`)
* **Miscellaneous info** — extra context for the AI to improve query generation

### Feedback

A free-text field (up to 2000 characters) providing global context about the datamart to guide AI behavior.

### Completion Score

A computed score (0–100) reflecting how thoroughly the semantic layer is filled out. Returned by the GET endpoint.