docs/api reference/deployments

Deployments API

Push model updates to robots, manage rollouts, and trigger rollbacks.

Endpoints

GET

/deployments

List all active deployments in your workspace.

POST

/deployments

Create a new deployment (push model to robot or fleet).

GET

/deployments/{id}

Get deployment status and progress.

POST

/deployments/{id}/complete

Complete a staged rollout (promote from partial to full).

POST

/deployments/{id}/rollback

Roll back to the previous model version.

DELETE

/deployments/{id}

Stop and remove a deployment.

List Deployments

GET/deployments

bash

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

json

// 200 OK
{
  "data": [
    {
      "id": "dep_abc789",
      "model_id": "mdl_abc123",
      "model_version": "v2",
      "target_type": "robot",
      "target_id": "rob_a1b2c3d4",
      "status": "active",
      "rollout_percent": 100,
      "deployed_at": "2026-03-20T09:00:00Z"
    }
  ],
  "total": 1
}

Create a Deployment

POST/deployments

Field	Type	Required	Description
model_id	string	Yes	ID of the model to deploy.
model_version	string	No	Version to deploy (e.g. v2). Defaults to active version.
robot_id	string	No	Target robot ID. Provide robot_id OR fleet_id.
fleet_id	string	No	Target fleet ID. Provide robot_id OR fleet_id.
rollout_percent	integer	No	Percentage of fleet to deploy to initially (1–100). Default: 100.
input_topic	string	No	Override the ROS 2 input topic. Default: robot type default.
output_topic	string	No	Override the ROS 2 output topic. Default: /kairo/inference.
namespace	string	No	ROS 2 namespace prefix for this deployment.

bash

# Deploy to a single robot
curl -X POST https://api.kairo.dev/v1/deployments \
  -H "Authorization: Bearer kai_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "mdl_abc123",
    "model_version": "v2",
    "robot_id": "rob_a1b2c3d4",
    "output_topic": "/kairo/inference"
  }'

bash

# Staged fleet rollout — 20% first
curl -X POST https://api.kairo.dev/v1/deployments \
  -H "Authorization: Bearer kai_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "mdl_abc123",
    "fleet_id": "flt_xyz123",
    "rollout_percent": 20
  }'

json

// 202 Accepted
{
  "id": "dep_newdep001",
  "status": "deploying",
  "target_type": "fleet",
  "target_id": "flt_xyz123",
  "total_robots": 24,
  "deployed_robots": 0,
  "rollout_percent": 20,
  "estimated_completion_s": 45
}

Get Deployment Status

GET/deployments/{id}

json

// 200 OK — staged rollout in progress
{
  "id": "dep_newdep001",
  "status": "partial",
  "model_id": "mdl_abc123",
  "model_version": "v2",
  "target_type": "fleet",
  "target_id": "flt_xyz123",
  "total_robots": 24,
  "deployed_robots": 5,
  "rollout_percent": 20,
  "deployed_at": "2026-03-23T12:00:00Z",
  "metrics_summary": {
    "avg_latency_p99_ms": 22,
    "error_rate": 0.001
  }
}

Rollback a Deployment

POST/deployments/{id}/rollback

bash

curl -X POST https://api.kairo.dev/v1/deployments/dep_abc789/rollback \
  -H "Authorization: Bearer kai_live_xxxxxxxxxxxx"

json

// 200 OK
{
  "deployment_id": "dep_abc789",
  "rolled_back_to_version": "v1",
  "status": "rolling_back",
  "estimated_completion_s": 5
}

ℹ

Rollbacks use the model version cached on each robot and complete in under 5 seconds — no re-download required. Rollback history is retained for 30 days.

←

Models API

Was this page helpful?