Skip to main content
POST
/
recording
/
start
Start Recording Episode
curl --request POST \
  --url https://api.example.com/recording/start \
  --header 'Content-Type: application/json' \
  --data '
{
  "add_metadata": {
    "bbox_position": [
      0.5,
      1,
      0,
      0.5
    ]
  },
  "branch_path": "<string>",
  "cameras_ids_to_record": [
    0,
    1
  ],
  "dataset_name": "example_dataset",
  "enable_rerun_visualization": false,
  "episode_format": "lerobot_v2.1",
  "freq": 30,
  "instruction": "Pick up the orange brick and put it in the black box.",
  "leader_arm_ids": [
    "/dev/ttyUSB0"
  ],
  "robot_serials_to_ignore": [
    "/dev/ttyUSB0"
  ],
  "save_cartesian": false,
  "target_video_size": [
    320,
    240
  ],
  "video_codec": "avc1"
}
'
import requests

url = "https://api.example.com/recording/start"

payload = {
"add_metadata": { "bbox_position": [0.5, 1, 0, 0.5] },
"branch_path": "<string>",
"cameras_ids_to_record": [0, 1],
"dataset_name": "example_dataset",
"enable_rerun_visualization": False,
"episode_format": "lerobot_v2.1",
"freq": 30,
"instruction": "Pick up the orange brick and put it in the black box.",
"leader_arm_ids": ["/dev/ttyUSB0"],
"robot_serials_to_ignore": ["/dev/ttyUSB0"],
"save_cartesian": False,
"target_video_size": [320, 240],
"video_codec": "avc1"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
add_metadata: {bbox_position: [0.5, 1, 0, 0.5]},
branch_path: '<string>',
cameras_ids_to_record: [0, 1],
dataset_name: 'example_dataset',
enable_rerun_visualization: false,
episode_format: 'lerobot_v2.1',
freq: 30,
instruction: 'Pick up the orange brick and put it in the black box.',
leader_arm_ids: ['/dev/ttyUSB0'],
robot_serials_to_ignore: ['/dev/ttyUSB0'],
save_cartesian: false,
target_video_size: [320, 240],
video_codec: 'avc1'
})
};

fetch('https://api.example.com/recording/start', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/recording/start",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'add_metadata' => [
'bbox_position' => [
0.5,
1,
0,
0.5
]
],
'branch_path' => '<string>',
'cameras_ids_to_record' => [
0,
1
],
'dataset_name' => 'example_dataset',
'enable_rerun_visualization' => false,
'episode_format' => 'lerobot_v2.1',
'freq' => 30,
'instruction' => 'Pick up the orange brick and put it in the black box.',
'leader_arm_ids' => [
'/dev/ttyUSB0'
],
'robot_serials_to_ignore' => [
'/dev/ttyUSB0'
],
'save_cartesian' => false,
'target_video_size' => [
320,
240
],
'video_codec' => 'avc1'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"strings"
"net/http"
"io"
)

func main() {

url := "https://api.example.com/recording/start"

payload := strings.NewReader("{\n \"add_metadata\": {\n \"bbox_position\": [\n 0.5,\n 1,\n 0,\n 0.5\n ]\n },\n \"branch_path\": \"<string>\",\n \"cameras_ids_to_record\": [\n 0,\n 1\n ],\n \"dataset_name\": \"example_dataset\",\n \"enable_rerun_visualization\": false,\n \"episode_format\": \"lerobot_v2.1\",\n \"freq\": 30,\n \"instruction\": \"Pick up the orange brick and put it in the black box.\",\n \"leader_arm_ids\": [\n \"/dev/ttyUSB0\"\n ],\n \"robot_serials_to_ignore\": [\n \"/dev/ttyUSB0\"\n ],\n \"save_cartesian\": false,\n \"target_video_size\": [\n 320,\n 240\n ],\n \"video_codec\": \"avc1\"\n}")

req, _ := http.NewRequest("POST", url, payload)

req.Header.Add("Content-Type", "application/json")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.example.com/recording/start")
.header("Content-Type", "application/json")
.body("{\n \"add_metadata\": {\n \"bbox_position\": [\n 0.5,\n 1,\n 0,\n 0.5\n ]\n },\n \"branch_path\": \"<string>\",\n \"cameras_ids_to_record\": [\n 0,\n 1\n ],\n \"dataset_name\": \"example_dataset\",\n \"enable_rerun_visualization\": false,\n \"episode_format\": \"lerobot_v2.1\",\n \"freq\": 30,\n \"instruction\": \"Pick up the orange brick and put it in the black box.\",\n \"leader_arm_ids\": [\n \"/dev/ttyUSB0\"\n ],\n \"robot_serials_to_ignore\": [\n \"/dev/ttyUSB0\"\n ],\n \"save_cartesian\": false,\n \"target_video_size\": [\n 320,\n 240\n ],\n \"video_codec\": \"avc1\"\n}")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.example.com/recording/start")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"add_metadata\": {\n \"bbox_position\": [\n 0.5,\n 1,\n 0,\n 0.5\n ]\n },\n \"branch_path\": \"<string>\",\n \"cameras_ids_to_record\": [\n 0,\n 1\n ],\n \"dataset_name\": \"example_dataset\",\n \"enable_rerun_visualization\": false,\n \"episode_format\": \"lerobot_v2.1\",\n \"freq\": 30,\n \"instruction\": \"Pick up the orange brick and put it in the black box.\",\n \"leader_arm_ids\": [\n \"/dev/ttyUSB0\"\n ],\n \"robot_serials_to_ignore\": [\n \"/dev/ttyUSB0\"\n ],\n \"save_cartesian\": false,\n \"target_video_size\": [\n 320,\n 240\n ],\n \"video_codec\": \"avc1\"\n}"

response = http.request(request)
puts response.read_body
{
  "message": "<string>",
  "status": "ok"
}
{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}

Body

application/json

Request to start the recording of an episode.

add_metadata
Add Metadata · object | null

Passing a dictionnary will store the value in each row of the recorded dataset. The key is the name of the column, and the value is a list. If set to None, no additional metadata is saved.

Example:
{ "bbox_position": [0.5, 1, 0, 0.5] }
branch_path
string | null

Path to the branch to push the dataset to, in addition to the main branch. If set to None, only push to the main branch. Defaults to None.

cameras_ids_to_record
integer[] | null

List of camera ids to record. If set to None, records all available cameras.

Example:
[0, 1]
dataset_name
string | null

Name of the dataset to save the episode in.If None, defaults to the value set in Admin Configuration.

Example:

"example_dataset"

enable_rerun_visualization
boolean
default:false

Enable rerun

episode_format
enum<string> | null

Format to save the episode. json is compatible with OpenVLA and stores videos as a series of npy. lerobot_v2 is compatible with lerobot training..If None, defaults to the value set in Admin Configuration.

Available options:
json,
lerobot_v2,
lerobot_v2.1
Example:

"lerobot_v2.1"

freq
integer | null

Records steps of the robot at this frequency.If None, defaults to the value set in Admin Configuration.

Example:

30

instruction
string | null

A text describing the recorded task. If set to None, defaults to the value set in Admin Configuration.

Example:

"Pick up the orange brick and put it in the black box."

leader_arm_ids
string[] | null

Serial numbers of the leader arms used during the recording

Example:
["/dev/ttyUSB0"]
robot_serials_to_ignore
string[] | null

List of robot serial ids to ignore. If set to None, records all available robots.

Example:
["/dev/ttyUSB0"]
save_cartesian
boolean
default:false

Record cartesian positions of the robots as well, this will make your dataset incompatible with lerobot and it only works for robots with simulators. Defaults to False.

target_video_size
Target Video Size · object | null

Target video size for the recording, all videos in the dataset should have the same size. If set to None, defaults to the value set in Admin Configuration.

Example:
[320, 240]
video_codec
enum<string> | null

Codec to use for the video saving.If None, defaults to the value set in Admin Configuration.

Available options:
avc1,
hev1,
mp4v,
hvc1,
avc3,
av01,
vp09,
av1
Example:

"avc1"

Response

Successful Response

Default response. May contain other fields.

message
string | null
status
enum<string>
default:ok
Available options:
ok,
error