docs/api reference/models

Models API

Trigger training runs, manage model versions, and export trained models.

Endpoints

GET

/models

List all models in your workspace.

GET

/models/{id}

Get a model and its latest metrics.

POST

/models/train

Start a new training run.

GET

/models/{id}/runs

List all training runs for a model.

GET

/models/{id}/runs/{runId}

Get details and logs for a training run.

POST

/models/{id}/promote

Promote a version to active.

POST

/models/{id}/export

Export a model as a ROS 2 package or ONNX file.

DELETE

/models/{id}

Delete a model and all its versions.

List Models

GET/models

bash

curl https://api.kairo.dev/v1/models \
  -H "Authorization: Bearer kai_live_xxxxxxxxxxxx"

json

// 200 OK
{
  "data": [
    {
      "id": "mdl_abc123",
      "name": "arm-model-v1",
      "task": "manipulation",
      "status": "active",
      "active_version": "v2",
      "accuracy": 0.943,
      "robot_id": "rob_a1b2c3d4",
      "created_at": "2026-02-01T09:00:00Z"
    }
  ],
  "total": 1
}

Start a Training Run

POST/models/train

Field	Type	Required	Description
dataset_id	string	Yes	ID of the preprocessed dataset to train on.
robot_id	string	Yes	Robot this model will be deployed to.
task	string	Yes	Task type: manipulation, navigation, object_detection, etc.
name	string	No	Human-readable name for the model.
architecture	string	No	Model architecture. Defaults to auto.
config	object	No	Training hyperparameters (epochs, learning_rate, batch_size).

bash

curl -X POST https://api.kairo.dev/v1/models/train \
  -H "Authorization: Bearer kai_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_id": "ds_xyz123",
    "robot_id": "rob_a1b2c3d4",
    "task": "manipulation",
    "name": "arm-model-v2",
    "config": {
      "epochs": 30,
      "learning_rate": 0.001,
      "batch_size": 64
    }
  }'

json

// 202 Accepted
{
  "model_id": "mdl_abc123",
  "run_id": "run_newrun456",
  "status": "queued",
  "position_in_queue": 1,
  "estimated_duration_s": 360
}

Get Training Run

GET/models/{id}/runs/{runId}

json

// 200 OK
{
  "run_id": "run_789abc",
  "model_id": "mdl_abc123",
  "status": "complete",
  "started_at": "2026-03-20T08:00:00Z",
  "completed_at": "2026-03-20T08:04:02Z",
  "duration_s": 242,
  "metrics": {
    "final_loss": 0.072,
    "val_loss": 0.091,
    "accuracy": 0.943,
    "val_accuracy": 0.931,
    "epochs_run": 20,
    "inference_latency_p99_ms": 28
  },
  "model_version": "v2",
  "artifact_size_mb": 48
}

Export a Model

POST/models/{id}/export

bash

curl -X POST https://api.kairo.dev/v1/models/mdl_abc123/export \
  -H "Authorization: Bearer kai_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "format": "ros2-pkg", "version": "v2" }'

json

// 200 OK
{
  "download_url": "https://exports.kairo.dev/mdl_abc123_v2.tar.gz",
  "expires_at": "2026-03-24T12:00:00Z",
  "format": "ros2-pkg",
  "size_mb": 52
}

ℹ

Export download links expire after 24 hours. Re-request the export endpoint to generate a new link.

←

Robots API

Deployments API

→

Was this page helpful?