ML Endpoints
The ML API provides endpoints for model training, feature engineering, model serving, and experiment tracking within the AI Service. These endpoints bridge the AI Service with the ML Service, enabling conversational interfaces for machine learning workflows.
Train Model
Submits a model training job with the specified configuration.
| Property | Value |
|---|---|
| Method | POST |
| Path | /api/v1/ml/train |
| Auth | JWT required |
Request Body
{
"name": "churn-predictor-v2",
"algorithm": "xgboost",
"dataset_id": "ds-customers-001",
"target_column": "churned",
"feature_columns": ["tenure", "monthly_charges", "total_charges", "contract_type"],
"hyperparameters": {
"n_estimators": 100,
"max_depth": 6,
"learning_rate": 0.1
},
"tenant_id": "acme-corp"
}Response
{
"job_id": "train-abc123",
"status": "submitted",
"model_name": "churn-predictor-v2",
"estimated_duration_minutes": 15,
"created_at": "2025-03-15T10:00:00Z"
}Get Training Status
Retrieves the status of a training job.
| Property | Value |
|---|---|
| Method | GET |
| Path | /api/v1/ml/train/:job_id |
| Auth | JWT required |
Response
{
"job_id": "train-abc123",
"status": "completed",
"progress": 100,
"metrics": {
"accuracy": 0.94,
"precision": 0.91,
"recall": 0.88,
"f1_score": 0.895,
"auc_roc": 0.96
},
"model_artifact_id": "model-xyz789",
"duration_seconds": 842
}Predict
Runs inference against a deployed model.
| Property | Value |
|---|---|
| Method | POST |
| Path | /api/v1/ml/predict |
| Auth | JWT required |
Request Body
{
"model_id": "model-xyz789",
"features": {
"tenure": 24,
"monthly_charges": 79.50,
"total_charges": 1908.00,
"contract_type": "month-to-month"
}
}Response
{
"prediction": 1,
"probability": 0.82,
"model_id": "model-xyz789",
"model_version": "v2",
"latency_ms": 12
}List Models
Returns registered models accessible to the tenant.
| Property | Value |
|---|---|
| Method | GET |
| Path | /api/v1/ml/models |
| Auth | JWT required |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| tenant_id | string | yes | Tenant identifier |
| status | string | no | Filter by status (training, ready, deployed, archived) |
| limit | integer | no | Max results (default 20) |
Get Features
Retrieves feature values from the feature store for a given entity.
| Property | Value |
|---|---|
| Method | POST |
| Path | /api/v1/ml/features |
| Auth | JWT required |
Request Body
{
"feature_set": "customer_features",
"entity_ids": ["cust-001", "cust-002"],
"features": ["tenure", "monthly_charges", "total_charges"]
}Response
{
"features": [
{
"entity_id": "cust-001",
"values": {"tenure": 24, "monthly_charges": 79.50, "total_charges": 1908.00}
}
]
}List Experiments
Returns experiment tracking data for model comparison.
| Property | Value |
|---|---|
| Method | GET |
| Path | /api/v1/ml/experiments |
| Auth | JWT required |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| tenant_id | string | yes | Tenant identifier |
| model_name | string | no | Filter by model name |
| limit | integer | no | Max results (default 20) |
Response
{
"experiments": [
{
"id": "exp-001",
"model_name": "churn-predictor",
"run_count": 12,
"best_metric": {"f1_score": 0.895},
"status": "active",
"created_at": "2025-03-10T08:00:00Z"
}
]
}