docs/api-reference

API Reference

The Artemis REST API lets you programmatically manage robots, trigger training runs, push deployments, and retrieve telemetry data.

Base URL

text

https://api.kairo.dev/v1

All API requests must be made over HTTPS. HTTP requests will be rejected.

Authentication

Authenticate by passing your API key in the Authorization header as a Bearer token:

bash

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

⚠

Never expose your API key in client-side code. Generate separate keys for CI/CD pipelines and local development. Keys can be rotated at any time from Dashboard → Settings → API Keys.

API keys carry three permission scopes:

read

Read robots, models, deployments, and telemetry.

write

Create and update robots, trigger training, push deployments.

admin

Manage team members, billing, and delete resources.

Rate Limits

Plan	Requests / min	Requests / day
Starter	60	1,000
Builder	300	10,000
Pro	Unlimited	Unlimited

When rate limited, the API returns 429 Too Many Requests. The Retry-After header indicates when to retry.

Robots

Manage your robot fleet.

Endpoints

GET

/robots

List all robots in your fleet.

POST

/robots

GET

/robots/{id}

Get a single robot by ID.

PUT

/robots/{id}

Update robot name or metadata.

DELETE

/robots/{id}

Remove a robot from the fleet.

GET

/robots/{id}/status

Get real-time status and telemetry.

Example — list all robots:

bash

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

# 200 OK
{
  "data": [
    {
      "id": "rob_a1b2c3d4",
      "name": "my-arm-01",
      "type": "manipulator",
      "status": "online",
      "ros_distro": "humble",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "total": 1
}

Models

Manage AI model training and versioning.

Endpoints

GET

/models

List all trained models.

POST

/models/train

Start a new training run.

GET

/models/{id}

Get model details and metrics.

GET

/models/{id}/runs

List training run history for a model.

POST

/models/{id}/export

Export model as a ROS 2 package.

DELETE

/models/{id}

Delete a model and its artifacts.

Example — start a training run:

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",
    "config": {
      "epochs": 20,
      "learning_rate": "auto"
    }
  }'

# 202 Accepted
{
  "run_id": "run_789abc",
  "status": "queued",
  "estimated_duration_s": 240
}

Deployments

Push models to robots and manage rollouts.

Endpoints

GET

/deployments

List all active deployments.

POST

/deployments

Deploy a model to a robot.

GET

/deployments/{id}

Get deployment status.

POST

/deployments/{id}/rollback

Roll back to the previous model version.

DELETE

/deployments/{id}

Stop and remove a deployment.

ℹ

Rollbacks are instant — Artemis keeps the previous model version cached on the robot for zero-downtime switching. Rollback history is retained for 30 days.

Error Codes

Code	Meaning
400	Bad Request — missing or invalid parameters.
401	Unauthorized — invalid or missing API key.
403	Forbidden — your key lacks the required scope.
404	Not Found — resource does not exist.
409	Conflict — e.g. a training run is already in progress.
429	Too Many Requests — rate limit exceeded.
500	Server Error — something went wrong on our end.

Was this page helpful?