Skip to main content

​
GET /api/v1/algorithm-models

List all algorithm models. Supports cursor-based pagination.

​
Response

{
  "data": [
    {
      "id": "model_001",
      "key": "propensity-credit-card",
      "name": "Credit Card Propensity",
      "modelType": "bayesian",
      "status": "active",
      "version": 3,
      "trainingSamples": 12500,
      "metrics": { "auc": 0.78, "accuracy": 0.82 },
      "lastTrainedAt": "2026-03-14T06:00:00.000Z",
      "createdAt": "2026-01-20T10:00:00.000Z"
    }
  ],
  "total": 5,
  "hasMore": false
}

​
POST /api/v1/algorithm-models

Create a new algorithm model.

​
Request Body

FieldTypeRequiredDescription
keystringYesUnique model key
namestringYesDisplay name
modelTypestringYes"scorecard", "bayesian", or "gradient_boosted"
descriptionstringNoDescription
statusstringNoDefault: "draft"
configobjectNoModel-specific configuration
targetFieldstringNoTarget variable field name
targetSchemaKeystringNoSchema key containing the target
predictorsarrayNoPredictor feature definitions
learningConfigobjectNoOnline learning configuration

​
Example

curl -X POST https://playground.kaireonai.com/api/v1/algorithm-models \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{
    "key": "propensity-credit-card",
    "name": "Credit Card Propensity",
    "modelType": "scorecard",
    "targetField": "converted",
    "targetSchemaKey": "customers",
    "predictors": ["income", "credit_score", "tenure_months"]
  }'
Response: 201 Created

​
GET /api/v1/algorithm-models/

Get model details including version history. Response: 200 OK with the model object and versions array.

​
PUT /api/v1/algorithm-models/

Update a model’s configuration, status, metrics, or learning config.

​
Request Body

All fields are optional. Only provided fields are updated.
FieldTypeDescription
namestringUpdated name
descriptionstringUpdated description
statusstringUpdated status
configobjectUpdated model config
targetFieldstringUpdated target field
predictorsarrayUpdated predictor list
metricsobjectUpdated metrics
modelStateobjectUpdated model state (weights, coefficients)
learningConfigobjectUpdated learning config
outcomeWeightsobjectPer-outcome scoring weights
interactionFeaturesobjectInteraction feature configuration
evolutionConfigobjectAuto-evolution tier thresholds
Response: 200 OK

​
DELETE /api/v1/algorithm-models/

Delete a model. Response: 204 No Content

​
POST /api/v1/algorithm-models//score

Score a single customer against the model.

​
Request Body

FieldTypeRequiredDescription
attributesobjectNoCustomer attribute vector

​
Response

{
  "score": 0.73,
  "contributions": [
    { "feature": "credit_score", "contribution": 0.25 },
    { "feature": "income", "contribution": 0.18 }
  ]
}

​
POST /api/v1/algorithm-models//score-offer-set

Score a set of offers for a customer. Returns per-offer propensity scores with optional interaction history features.

​
Request Body

FieldTypeRequiredDescription
customerAttributesobjectNoCustomer feature vector
offersarrayYesArray of { id, name?, attributes }
customerIdstringNoIf provided, fetches real interaction summaries from DB
contextobjectNoReal-time context features

​
Response

{
  "modelId": "model_001",
  "modelKey": "propensity-credit-card",
  "modelType": "bayesian",
  "customerId": "CUST001",
  "count": 3,
  "scores": [
    { "offerId": "offer_001", "score": 0.87, "rank": 1 },
    { "offerId": "offer_002", "score": 0.65, "rank": 2 },
    { "offerId": "offer_003", "score": 0.42, "rank": 3 }
  ]
}

​
POST /api/v1/algorithm-models//train

Train (or retrain) a model. Creates a new version snapshot and updates metrics history.

​
Response

Returns the updated model with incremented version, refreshed metrics, and status set to "active".

​
POST /api/v1/algorithm-models//upgrade

Upgrade a model to the next tier (scorecard to bayesian, or bayesian to gradient_boosted). Optionally creates a champion/challenger experiment.

​
Request Body

FieldTypeRequiredDescription
createExperimentbooleanNoIf true, auto-creates a 50/50 experiment. Default: false

​
Response

{
  "upgraded": { "id": "model_002", "modelType": "bayesian", "status": "draft" },
  "experiment": { "id": "exp_001", "name": "Credit Card Propensity: Champion vs Bayesian Upgrade" }
}
Response: 201 Created

​
GET /api/v1/algorithm-models//evolution-history

View model evolution config, progress toward the next tier, and a timeline of version transitions.

​
Response

{
  "modelId": "model_001",
  "modelKey": "propensity-credit-card",
  "currentModelType": "bayesian",
  "evolutionConfig": {
    "autoEvolve": true,
    "currentTier": "bayesian",
    "targetTier": "gradient_boosted",
    "thresholds": {
      "gradientBoostedSamples": 5000,
      "gradientBoostedAuc": 0.75
    }
  },
  "progress": {
    "nextTier": "gradient_boosted",
    "progressPct": 68,
    "readyToEvolve": false,
    "details": {
      "samplesRequired": 5000,
      "samplesActual": 3400,
      "aucRequired": 0.75,
      "aucActual": 0.78
    }
  },
  "timeline": [
    { "version": 3, "modelType": "bayesian", "metrics": { "auc": 0.78 }, "createdAt": "2026-03-14T06:00:00.000Z" }
  ]
}

​
Roles

EndpointAllowed Roles
GET /algorithm-modelsadmin, editor, viewer
POST /algorithm-modelsadmin, editor
PUT /algorithm-models/{id}admin, editor
DELETE /algorithm-models/{id}admin, editor
POST /{id}/scoreany authenticated
POST /{id}/score-offer-setany authenticated
POST /{id}/trainadmin, editor
POST /{id}/upgradeadmin, editor
GET /{id}/evolution-historyany authenticated
See also: Algorithms & Models