ML Models API

List ML Models

Returns all ML models for a project.

curl -X GET "http://localhost:8080/api/ml-models?project_id=proj-123"

Query Parameters

project_id

string

required

Filter by project ID

Response

models

array

Array of ML model objects

Show MLModel Object

string

Model ID

project_id

string

Associated project ID

ontology_id

string

Associated ontology ID

name

string

Model name

description

string

Model description

type

string

Model type: decision_tree, random_forest, regression, or neural_network

status

string

Status: draft, training, trained, failed, degraded, deprecated, or archived

version

string

Model version

is_recommended

boolean

Whether this was the recommended type

recommendation_score

number

Score from recommendation engine

model_artifact_path

string

Path to trained model file

created_at

string

ISO 8601 timestamp

updated_at

string

ISO 8601 timestamp

trained_at

string

ISO 8601 timestamp

Create ML Model

Creates a new ML model record (training must be triggered separately).

curl -X POST http://localhost:8080/api/ml-models \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj-123",
    "ontology_id": "onto-456",
    "name": "Temperature Predictor",
    "description": "Predicts temperature based on sensor data",
    "type": "neural_network",
    "training_config": {
      "train_test_split": 0.8,
      "random_seed": 42,
      "learning_rate": 0.001,
      "batch_size": 32
    }
  }'

Request Body

project_id

string

required

Project ID to associate with

ontology_id

string

required

Ontology ID defining the data schema

name

string

required

Model name

description

string

Model description

type

string

required

Model type: decision_tree, random_forest, regression, or neural_network

training_config

object

Training configuration

Show TrainingConfig

train_test_split

number

Split ratio (e.g., 0.8 for 80% train, 20% test)

random_seed

number

Random seed for reproducibility

max_iterations

number

Maximum training iterations

learning_rate

number

Learning rate

batch_size

number

Batch size

early_stopping_rounds

number

Early stopping rounds

hyperparameters

object

Additional hyperparameters

metadata

object

Additional metadata (key-value pairs)

Response

Returns the created ML model object with status draft.

Get ML Model

Returns a single ML model by ID.

curl -X GET http://localhost:8080/api/ml-models/model-123

Path Parameters

string

required

Model ID

Response

Returns the ML model object (see List ML Models for schema).

Update ML Model

Updates an ML model’s metadata or status.

curl -X PUT http://localhost:8080/api/ml-models/model-123 \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated model description",
    "status": "archived"
  }'

Path Parameters

string

required

Model ID

Request Body

All fields are optional. Only provided fields will be updated.

name

string

New name

description

string

New description

status

string

New status: draft, training, trained, failed, degraded, deprecated, or archived

training_metrics

object

Updated training metrics

performance_metrics

object

Updated performance metrics

metadata

object

Updated metadata

Response

Returns the updated ML model object.

Delete ML Model

Deletes an ML model.

curl -X DELETE http://localhost:8080/api/ml-models/model-123

Path Parameters

string

required

Model ID

Response

Returns 204 No Content on success.

Trigger Model Training

Enqueues a Kubernetes training job for the specified model. Returns 202 Accepted immediately; poll the model’s status field or listen on the WebSocket for completion.

curl -X POST http://localhost:8080/api/ml-models/train \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "model-123",
    "storage_ids": ["storage-456", "storage-789"],
    "training_config": {
      "train_test_split": 0.8,
      "random_seed": 42
    }
  }'

Request Body

model_id

string

required

Model ID to train

storage_ids

array

Storage config IDs to use for training data. If empty, worker generates synthetic data for demo purposes.

training_config

object

Training configuration (overrides model’s default config)

Response

Returns the ML model object with status updated to training and HTTP status 202 Accepted.

Analyses the project’s ontology and returns a suggested model type (e.g., decision_tree, neural_network) along with a confidence score.

curl -X POST http://localhost:8080/api/ml-models/recommend \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj-123",
    "ontology_id": "onto-456"
  }'

Request Body

project_id

string

required

Project ID

ontology_id

string

required

Ontology ID to analyze

Response

recommended_type

string

Recommended model type

score

number

Confidence score (0-100)

reasoning

string

Human-readable explanation

all_scores

object

Scores for all model types

ontology_analysis

object

Analysis of the ontology

Show OntologyAnalysis

num_entities

number

Number of entities

num_attributes

number

Number of attributes

num_relationships

number

Number of relationships

numerical_ratio

number

Ratio of numerical attributes

categorical_ratio

number

Ratio of categorical attributes

complexity

string

Complexity level: low, medium, or high

data_analysis

object

Analysis of ingested data

Show DataAnalysis

size

string

Data size: small, medium, or large

record_count

number

Number of records

has_unstructured

boolean

Whether unstructured data is present

feature_count

number

Number of features

Worker Callbacks

These endpoints are called by Kubernetes training jobs to report completion or failure.

Report Training Complete

Called by the worker job to record the trained artifact path and performance metrics.

curl -X POST http://localhost:8080/api/ml-models/model-123/training/complete \
  -H "Content-Type: application/json" \
  -d '{
    "model_artifact_path": "s3://models/model-123/v1.pkl",
    "performance_metrics": {
      "accuracy": 0.95,
      "f1_score": 0.93,
      "precision": 0.94,
      "recall": 0.92
    },
    "training_metrics": {
      "epoch": 50,
      "training_loss": 0.05,
      "validation_loss": 0.08
    }
  }'

Path Parameters

string

required

Model ID

Request Body

model_artifact_path

string

required

Path to the trained model artifact

performance_metrics

object

Model performance metrics

training_metrics

object

Training metrics

Response

{
  "status": "training completed"
}

Report Training Failure

Called by the worker job to record a training failure reason.

curl -X POST http://localhost:8080/api/ml-models/model-123/training/fail \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Insufficient training data"
  }'

Path Parameters

string

required

Model ID

Request Body

reason

string

required

Failure reason

Response

{
  "status": "training failed"
}

Overview

Endpoints

List ML Models

Query Parameters

Response

Create ML Model

Request Body

Response

Get ML Model

Path Parameters

Response

Update ML Model

Path Parameters

Request Body

Response

Delete ML Model

Path Parameters

Response

Trigger Model Training

Request Body

Response

Request Body

Response

Worker Callbacks

Report Training Complete

Path Parameters

Request Body

Response

Report Training Failure

Path Parameters

Request Body

Response

Build docs developers (and LLMs) love

Overview

Endpoints

​List ML Models

​Query Parameters

​Response

​Create ML Model

​Request Body

​Response

​Get ML Model

​Path Parameters

​Response

​Update ML Model

​Path Parameters

​Request Body

​Response

​Delete ML Model

​Path Parameters

​Response

​Trigger Model Training

​Request Body

​Response

​Recommend Model Type

​Request Body

​Response

​Worker Callbacks

​Report Training Complete

​Path Parameters

​Request Body

​Response

​Report Training Failure

​Path Parameters

​Request Body

​Response

Build docs developers (and LLMs) love

List ML Models

Query Parameters

Response

Create ML Model

Request Body

Response

Get ML Model

Path Parameters

Response

Update ML Model

Path Parameters

Request Body

Response

Delete ML Model

Path Parameters

Response

Trigger Model Training

Request Body

Response

Recommend Model Type

Request Body

Response

Worker Callbacks

Report Training Complete

Path Parameters

Request Body

Response

Report Training Failure

Path Parameters

Request Body

Response