Checkpoints (Saved Models)

Checkpoints are snapshots of a trained model at a point in time. They capture the model, its configuration, and feature settings so you can use a specific model version for predictions and scenarios.

Listing Checkpoints

GET /api/v1/projects/{projectId}/checkpoints

curl "https://kanva.human-driven.ai/api/v1/projects/{projectId}/checkpoints" \
  -H "X-API-Key: your_api_key"

Response:

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000000",
      "projectId": "...",
      "label": "SalesModel_20260205",
      "description": "Weekly retrain",
      "createdAt": "2026-02-05T12:00:00Z",
      "createdBy": "user@example.com",
      "isDefault": true,
      "linkedCheckpointId": null,
      "modelName": "LightGBM",
      "primaryMetricValue": 0.042,
      "targetMetric": "MAE"
    }
  ]
}

Field	Description
isDefault	Whether this is the project's default checkpoint
linkedCheckpointId	If this checkpoint was auto-created alongside another (e.g. during scenario creation), this links to the main checkpoint
primaryMetricValue	The target metric score at the time the checkpoint was saved

Getting Checkpoint Details

GET /api/v1/projects/{projectId}/checkpoints/{checkpointId}

Returns full details including training metrics, input features, and feature engineering configuration.

Creating a Checkpoint

POST /api/v1/projects/{projectId}/checkpoints

Saves the current trained model as a new checkpoint. This is an async operation — model artifacts are copied in the background.

import requests

API_URL = "https://kanva.human-driven.ai/api/v1"
API_KEY = "your_api_key"
PROJECT_ID = "your-project-id"

response = requests.post(
    f"{API_URL}/projects/{PROJECT_ID}/checkpoints",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "label": "Production v2",
        "description": "Weekly retrain with new features",
        "setAsDefault": True
    }
)

Request Fields

Field	Type	Required	Description
label	string	No	2-100 characters. Auto-generated from project name + date if omitted
description	string	No	Optional description
setAsDefault	bool	No	Mark as the project's default checkpoint

tip

The first checkpoint in a project is always set as default, regardless of setAsDefault.

Response

Returns 202 Accepted. The checkpoint is created asynchronously because model artifacts need to be copied.

{
  "success": true,
  "data": {
    "message": "Checkpoint creation initiated. Connect via SignalR for completion notification."
  }
}

Label Uniqueness

Labels must be unique within a project. If you provide a label that already exists, the API returns a 400 error. When auto-generating, the system appends _02, _03, etc. to avoid conflicts.

Updating a Checkpoint

PUT /api/v1/projects/{projectId}/checkpoints/{checkpointId}

Update a checkpoint's label, description, or default status.

curl -X PUT "https://kanva.human-driven.ai/api/v1/projects/{projectId}/checkpoints/{checkpointId}" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Production v2 (retrained)",
    "setAsDefault": true
  }'

Deleting a Checkpoint

DELETE /api/v1/projects/{projectId}/checkpoints/{checkpointId}

Returns 202 Accepted. Deletion is async because model artifacts are removed from storage.

warning

A checkpoint cannot be deleted if it is referenced by any scenario. Delete the scenarios first.

Limits

Constraint	Value
Max checkpoints per project	20
Label length	2-100 characters
Folder name length	Max 50 characters (derived from label)

Error Responses

Code	Cause
400	Duplicate label
400	No trained model available
400	Checkpoint limit reached (max 20)
400	Checkpoint is in use by scenarios (on delete)
404	Project or checkpoint not found

See Error Handling for the general error response format.