Models
Endpoints for listing, training and deleting bandit models.
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
Starts a training run in the background. The model pulls the latest observation data from your warehouse, updates its posterior, and publishes it for posterior queries.
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-factor exploration bias. Higher values increase exploration for that factor. |
Response:
202 Accepted:
{
"model_id": "4754cae0-9a5d-4691-91af-6d15ccc1f82e",
"status": "training",
"message": "Training started",
"meta": {
"request_id": "req_abc123",
"organization_id": "org_xyz"
}
}The model's status turns trained (or failed) when the run finishes. If a run is already in progress, the response says so and no second run starts.
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"
}
}