Create a Custom Model

A Custom Model combines a Provider Model (the underlying language model) with one or more Datasources. Once created, users can start sessions against it to ask analytical questions in natural language.

This use case describes how to create a Custom Model entirely via API — the same workflow the Lakehousecat UI performs internally.

Prerequisites

Before creating a Custom Model you need:

1. A Provider Model configured with valid API credentials (Anthropic, OpenAI, Google, AWS, or Azure). Configure this in the Lakehousecat UI under Models → Provider Models, or retrieve the ID of an existing one via API.
2. At least one Datasource with semantic extraction completed. See Manage Datasources.

CLI Alternative

If you have the lhc CLI configured, you can create a Custom Model in a single command:

# 1. Find the provider model ID
lhc models list --output json

# 2. Create Provider Model (admin only, if not already present)
lhc models create \
  --id azure-chat \
  --name "Azure GPT-4o" \
  --provider-type Azure \
  --provider-model-type Chat

# 3. Create Custom Model with datasource linked
lhc models create \
  --id sales-model \
  --name "Sales Intelligence" \
  --base-model-id azure-chat \
  --datasource-id 1223

The --datasource-id flag can be repeated to link multiple datasources at creation time.

See lhc models for full CLI reference.

---

API Sequence Overview

1. Get provider model ID
2. Create custom model
3. Bind datasource to model
4. (Optional) Share with users or groups

1. Get a Provider Model ID

List the available provider models to find the one you want to use:

curl -s "$LHC_CORE/api/v1/lhc/models?type=provider" \
  -H "Authorization: Bearer $LHC_TOKEN"

provider_models = requests.get(
    f"{CORE}/api/v1/lhc/models",
    headers=HEADERS,
    params={"type": "provider"},
).json()

for m in provider_models:
    print(m["id"], m["name"], m.get("provider"))

provider_model_id = provider_models[0]["id"]  # pick the one you want

2. Create the Custom Model

curl -X POST "$LHC_CORE/api/v1/lhc/models" \
  -H "Authorization: Bearer $LHC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Intelligence",
    "provider_model_id": "<provider-model-id>"
  }'

model = requests.post(
    f"{CORE}/api/v1/lhc/models",
    headers=HEADERS,
    json={
        "name": "Sales Intelligence",
        "provider_model_id": provider_model_id,
    },
).json()

model_id = model["id"]
print(f"Created model: {model_id}")

The response returns the full model object including id, name, and created_at.

3. Bind a Datasource to the Model

After creating the model, bind one or more datasources to it. Each datasource must have completed semantic extraction before binding.

curl -X POST "$LHC_SEMANTIC/api/v1/semantic/datasourcemodels" \
  -H "Authorization: Bearer $LHC_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"datasource_id\": \"$DATASOURCE_ID\", \"model_id\": \"$MODEL_ID\"}"

requests.post(
    f"{SEMANTIC}/api/v1/semantic/datasourcemodels",
    headers=HEADERS,
    json={
        "datasource_id": datasource_id,
        "model_id": model_id,
    },
)

You can bind multiple datasources to the same model by repeating this call with different datasource_id values.

4. Share with Users or Groups (Optional)

To make the model accessible to specific users or groups:

# Share with a user
curl -X POST "$LHC_CORE/api/v1/lhc/modelusers" \
  -H "Authorization: Bearer $LHC_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"model_id\": \"$MODEL_ID\", \"user_id\": \"<user-id>\"}"

# Share with a group
curl -X POST "$LHC_CORE/api/v1/lhc/modelgroups" \
  -H "Authorization: Bearer $LHC_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"model_id\": \"$MODEL_ID\", \"group_id\": \"<group-id>\"}"

# Share with a user
requests.post(
    f"{CORE}/api/v1/lhc/modelusers",
    headers=HEADERS,
    json={"model_id": model_id, "user_id": "<user-id>"},
)

# Share with a group
requests.post(
    f"{CORE}/api/v1/lhc/modelgroups",
    headers=HEADERS,
    json={"model_id": model_id, "group_id": "<group-id>"},
)

By default, a newly created model is only accessible to Admins and Builders. Sharing with users or groups makes it available in their session model selector.

Verify: List Models

Confirm the model was created and is visible:

models = requests.get(f"{CORE}/api/v1/lhc/models", headers=HEADERS).json()
for m in models:
    print(m["id"], m["name"])

Next Steps

The model is ready. Use it in Session Completions by passing model_id in the completion request.