Create Model

Page Outline

• Request Body
• Behavior
• Response

---

Creates a new model record in Model Studio, initializing it with the provided metadata and configuration.

Base Path: /api/v1/models

Method: POST

Path: /

Auth: Requires a valid Bearer token (Authorization: Bearer <JWT>)

Request Body

{
  "name": "My Churn Predictor",
  "description": "Binary classification model to predict customer churn.",
  "model_type": "auto",
  "task_type": "classification",
  "dataset_id": "ds-abc123",
  "tags": ["churn", "production"],
  "config": {
    "target_column": "churned",
    "feature_columns": ["age", "tenure", "monthly_spend"],
    "algorithm": "xgboost"
  }
}

Field	Type	Required	Description
name	string	✅	Human-readable name for the model
description	string	❌	Optional description of the model's purpose
model_type	string	✅	"auto" or "custom"
task_type	string	✅	"classification", "regression", or "clustering"
dataset_id	string	❌	ID of the dataset to link at creation time
tags	string[]	❌	Labels for filtering and organization
config	object	❌	Training configuration override

Behavior

• Validates that name is unique within the caller's organization scope.
• If dataset_id is provided, the dataset is linked immediately and its schema is validated against config.feature_columns.
• model_type: "custom" models are created in a draft state and require asset upload before training can be triggered.
• An audit log entry is written with action model.created, recording the caller's user ID, IP, and timestamp.
• Returns HTTP 409 Conflict if a model with the same name already exists.

Response

Returns a Model object representing the newly created record.

{
  "id": "mdl-7f3a19bc",
  "name": "My Churn Predictor",
  "description": "Binary classification model to predict customer churn.",
  "model_type": "auto",
  "task_type": "classification",
  "status": "draft",
  "version": 1,
  "created_at": "2026-03-13T11:00:00Z",
  "updated_at": "2026-03-13T11:00:00Z",
  "created_by": "user-001"
}