Skip to main content
POST
Create Twin

Authorizations

Authorization
string
header
required

A Kite API key (kite_...), from Platform API → Keys in the dashboard.

Headers

Idempotency-Key
string | null
Maximum string length: 255
authorization
string | null
X-Impersonation-Token
string | null
Kite-Version
enum<string>
default:2026-09-27

The dated contract your code was written against. Without it you get 2026-09-27; every response says which version served it.

Available options:
2026-09-27

Body

application/json

Build a digital twin from one episode of a Hugging Face LeRobot dataset. Only source is required.

source
TwinSource · object
required

Where the episode comes from. The same shape as an augmentation's source.

name
string | null

A short name for the twin

Maximum string length: 100
task
string | null

Which objects to author: the ones the robot manipulates. Defaults to a general manipulation brief

Maximum string length: 4000
prompt
string | null

How to describe the room to the reconstructor

Maximum string length: 4000
camera
string | null

Substring of the camera that seeds the room (see /v1/twins/validate)

Maximum string length: 200
wrist_camera
string | null
Maximum string length: 200
ceiling_m
number
default:2.9

Floor-to-ceiling height: the scale anchor

webhook_metadata
Webhook Metadata · object | null

Opaque metadata echoed on the resource and its webhook events

Response

The twin, queued

One digital twin.

id
string
required

twin_ + a time-ordered ULID

status
enum<string>
required
Available options:
queued,
processing,
canceling,
succeeded,
failed,
canceled
progress
number
required
Required range: 0 <= x <= 1
source
TwinSource · object
required

Where the episode comes from. The same shape as an augmentation's source.

object
enum<string>
default:twin
Available options:
twin
Allowed value: "twin"
stage
string | null

The stage running now

status_message
string | null
eta_seconds
integer | null

While queued or processing: time left, from the stages' typical durations

error
TwinError · object | null
camera
TwinCamera · object | null

What the dataset check resolved

config
Config · object

The build options given at create

stages
TwinStage · object[]

Every finished stage, in order

download
TwinDownload · object | null

Once succeeded: the whole scene as one .tar.gz. Its file list is GET /v1/twins/{id}/files

webhook_metadata
Webhook Metadata · object | null
created_at
string | null