Models
Endpoints for training bandit models and inspecting model state.
All endpoints are under /api/v2/models. All requests require an Authorization: Bearer <token> header.
List models
GET /api/v2/modelsAuth: Required
Returns all models in the organization.
Response:
{
"models": [
{
"id": "4754cae0-9a5d-4691-91af-6d15ccc1f82e",
"model_type": "cmab",
"status": "trained",
"training_data_config": {
"design_factors": [...],
"context_factors": [...],
"reward": { "name": "signup", "type": "bool" },
"attribution": { "type": "last_touch", "conversion_window_hours": 24 }
},
"created_at": "2026-01-15T10:30:00Z",
"updated_at": "2026-03-28T12:00:00Z"
}
],
"meta": {
"request_id": "req_abc123",
"organization_id": "org_xyz"
}
}Train model
POST /api/v2/models/:id/trainAuth: Required
Triggers a training run for the model. The model pulls the latest observation data from your warehouse and updates its posterior distributions.
Path parameters:
| Parameter | Type | Description |
|---|---|---|
id | string (UUID) | Model ID |
Request body (optional):
{
"bias": {
"headline": 0.1,
"cta_text": 0.05
}
}| Field | Type | Required | Description |
|---|---|---|---|
bias | object | No | Per-feature exploration bias. Higher values increase exploration for that feature. |
Response:
{
"model_id": "4754cae0-9a5d-4691-91af-6d15ccc1f82e",
"status": "trained",
"in_sample_metrics": {
"historic_reward": 0.24,
"expected_reward": {
"mean": 0.31,
"ci_lower": 0.27,
"ci_upper": 0.35
}
},
"meta": {
"request_id": "req_abc123",
"organization_id": "org_xyz"
}
}The in_sample_metrics.historic_reward is the observed reward rate in the training data. The expected_reward object contains the model's predicted reward rate with confidence intervals, showing the estimated improvement from the bandit's allocation strategy.
Delete model
DELETE /api/v2/models/:idAuth: Required
Soft-deletes the model. This does not delete the parent optimization, but the optimization will no longer be able to serve variants until a new model is created.
Path parameters:
| Parameter | Type | Description |
|---|---|---|
id | string (UUID) | Model ID |
Response:
{
"id": "4754cae0-9a5d-4691-91af-6d15ccc1f82e",
"status": "archived",
"meta": {
"request_id": "req_abc123",
"organization_id": "org_xyz"
}
}