Prediction Scenarios

A scenario is an input dataset linked to a saved model (checkpoint) that produces a set of predictions you can compare side by side.

Creating a Scenario

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

Every scenario must be linked to a checkpoint. You can either reference an existing checkpoint or save the current model as a new one in the same request.

Using an Existing Checkpoint

curl -X POST "https://kanva.human-driven.ai/api/v1/projects/{projectId}/scenarios" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "January Forecast",
    "checkpointId": "a1b2c3d4-0000-0000-0000-000000000000"
  }'

tip

Use GET /api/v1/projects/{projectId}/checkpoints to list available checkpoints. See Checkpoints for details.

Saving the Current Model as a New Checkpoint

Omit checkpointId to snapshot the latest trained model before creating the scenario:

curl -X POST "https://kanva.human-driven.ai/api/v1/projects/{projectId}/scenarios" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "January Forecast",
    "checkpointLabel": "Production v2"
  }'

If checkpointLabel is omitted, a label is auto-generated from the project name and date (e.g. SalesModel_20260205).

Request Fields

Field	Type	Required	Description
title	string	Yes	Scenario name
description	string	No	Optional description
color	string	No	Hex color for display (default #3498db)
checkpointId	GUID	No	Existing checkpoint to use. If omitted, a new checkpoint is created from the current model
checkpointLabel	string	No	Custom label when creating a new checkpoint (checkpointId omitted)
fileData	string	No	Base64 encoded CSV. Omit to auto-generate
fileName	string	No	Original filename (when uploading)
endDate	datetime	No	End date for auto-generated scenarios
dependentProjectCheckpoints	object	No	Checkpoints for dependent projects (see below)

Response

The endpoint returns 202 Accepted with a job ID. Scenario creation runs asynchronously because it may involve copying model artifacts and generating predictions.

{
  "success": true,
  "data": {
    "jobId": "f5e6d7c8-0000-0000-0000-000000000000",
    "status": "Pending"
  }
}

Poll GET /api/v1/jobs/project/{projectId} to check job status.

Uploading a Scenario File

To provide your own input data instead of auto-generating, encode the CSV as Base64:

import base64
import requests

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

# Read and encode the CSV
with open("scenario_input.csv", "rb") as f:
    file_data = base64.b64encode(f.read()).decode("utf-8")

response = requests.post(
    f"{API_URL}/projects/{PROJECT_ID}/scenarios",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "title": "Custom Input Scenario",
        "checkpointId": "a1b2c3d4-0000-0000-0000-000000000000",
        "fileData": file_data,
        "fileName": "scenario_input.csv"
    }
)

Dependent Project Checkpoints

If your project uses predictions from other projects as input features, you must provide checkpoints for those dependent projects too. This ensures the scenario always uses the same model versions for reproducible results.

response = requests.post(
    f"{API_URL}/projects/{PROJECT_ID}/scenarios",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "title": "Combined Forecast Q1",
        "checkpointId": "a1b2c3d4-0000-0000-0000-000000000000",
        "dependentProjectCheckpoints": {
            # dependent project ID -> checkpoint ID from that project
            "b2c3d4e5-0000-0000-0000-000000000000": "c3d4e5f6-0000-0000-0000-000000000000"
        }
    }
)

Auto-Creating Dependent Checkpoints

Use null as the checkpoint value to save the current model for a dependent project:

{
  "title": "Combined Forecast Q1",
  "dependentProjectCheckpoints": {
    "b2c3d4e5-0000-0000-0000-000000000000": null
  }
}

This creates checkpoints for both the main project and the dependent project in a single batch operation. The dependent checkpoint is automatically linked to the main one via linkedCheckpointId.

Error Responses

Code	Cause
400	No trained model available (when creating a new checkpoint)
400	Checkpoint limit reached (max 20 per project)
400	Dependent project has no saved models
404	Project or checkpoint not found

See Error Handling for the general error response format.