Semantic API

The Semantic API manages data sources and the semantic layer that enables natural language queries against your data. It is the foundation of Lakehousecat's AI-driven data access — connecting raw data to the language models that answer user questions.

Base URL: http://<host>:42018

What you can do

• Connect and manage data sources (databases, object storage, file uploads, lake formats)
• Trigger and monitor semantic extraction (schema analysis and description generation)
• Manage descriptions — human-readable metadata for tables and columns
• Configure hierarchies for multi-level data structures
• Control data source access by sharing with users and groups
• Bind data sources to custom models (/datasourcemodels)

Authentication

All endpoints require a Bearer token. Generate your API key in the Lakehousecat UI:

Account Settings → Security → API Keys → Generate API Key

Authorization: Bearer <your-api-key>

Key Concepts

Data Source — A connection to an external data store (PostgreSQL, MySQL, S3, Delta Lake, etc.). The Semantic API manages the lifecycle of these connections.

Semantic Extraction — The process by which Lakehousecat reads the schema of a data source and generates descriptions for tables and columns using an LLM. This is what enables natural language queries.

Descriptions — AI-generated or manually edited summaries of tables and columns. Good descriptions are essential for accurate query results.

Hierarchies — Structured relationships between data dimensions (e.g., Country → Region → City). These help the model understand drill-down paths in your data.

Quick Start

List your data sources

curl -X GET "http://localhost:42018/api/v1/semantic/datasources" \
  -H "Authorization: Bearer <your-api-key>"

import requests

BASE_URL = "http://localhost:42018"
HEADERS = {"Authorization": "Bearer <your-api-key>"}

response = requests.get(f"{BASE_URL}/api/v1/semantic/datasources", headers=HEADERS)
datasources = response.json()

Get a specific data source

curl -X GET "http://localhost:42018/api/v1/semantic/datasources/{datasource_id}" \
  -H "Authorization: Bearer <your-api-key>"

datasource_id = "ds-abc123"
response = requests.get(
    f"{BASE_URL}/api/v1/semantic/datasources/{datasource_id}",
    headers=HEADERS,
)
datasource = response.json()

Trigger a semantic extraction

Semantic extraction reads the data source schema and generates descriptions for all tables and columns. This is required before a data source can be used in a custom model.

curl -X POST "http://localhost:42018/api/v1/semantic/semanticextractions" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"datasource_id": "ds-abc123"}'

response = requests.post(
    f"{BASE_URL}/api/v1/semantic/semanticextractions",
    json={"datasource_id": "ds-abc123"},
    headers=HEADERS,
)
extraction = response.json()

List descriptions for a data source

curl -X GET "http://localhost:42018/api/v1/semantic/descriptions?datasource_id=ds-abc123" \
  -H "Authorization: Bearer <your-api-key>"

response = requests.get(
    f"{BASE_URL}/api/v1/semantic/descriptions",
    params={"datasource_id": "ds-abc123"},
    headers=HEADERS,
)
descriptions = response.json()

Share a data source with a group

curl -X POST "http://localhost:42018/api/v1/semantic/datasources/{datasource_id}/share/group" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"group_id": "group-456"}'

response = requests.post(
    f"{BASE_URL}/api/v1/semantic/datasources/{datasource_id}/share/group",
    json={"group_id": "group-456"},
    headers=HEADERS,
)

Bind a data source to a custom model

curl -X POST "http://localhost:42018/api/v1/semantic/datasourcemodels" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"datasource_id": "ds-abc123", "model_id": "model-789"}'

response = requests.post(
    f"{BASE_URL}/api/v1/semantic/datasourcemodels",
    json={"datasource_id": "ds-abc123", "model_id": "model-789"},
    headers=HEADERS,
)

Endpoint Groups

Resource	Path	Description
Data Sources	/api/v1/semantic/datasources	Full data source lifecycle
Datasource Models	/api/v1/semantic/datasourcemodels	Bind data sources to models
Datasource Groups	/api/v1/semantic/datasourcegroups	Share data sources with groups
Datasource Users	/api/v1/semantic/datasourceusers	Share data sources with users
Descriptions	/api/v1/semantic/descriptions	Table and column descriptions
Hierarchies	/api/v1/semantic/hierarchies	Dimension hierarchies
Semantic Extractions	/api/v1/semantic/semanticextractions	Trigger and monitor extractions

Typical Workflow

When setting up a data source programmatically, follow this order:

1. Create a data source (POST /datasources)
2. Trigger semantic extraction (POST /semanticextractions)
3. Review and edit descriptions (GET /descriptions, PUT /descriptions/{id})
4. Configure hierarchies if needed (POST /hierarchies)
5. Bind the data source to a custom model (POST /datasourcemodels)
6. Share with users or groups (POST /datasources/{id}/share/group)

UI Equivalent

Data source configuration done via this API corresponds to the Data workspace in the Lakehousecat UI, including the editor tabs: General, Filters, Descriptions, Hierarchies, and Operations.