Skip to content
Docs menu

repos

Repos (kind = dataset | model | robot) — create, read, update, delete, search

5 operations · 33 schemas

GET /v1/repos

List / search repos

listRepos · scope none

Lists repos visible to the caller (public + own/org private). q matches slug and description (case-insensitive substring, v0); tag may repeat and every given tag must match.

Parameters

listRepos parameters
NameInTypeDescription
qquerystring

length ≤ 256

Search text (matches slug and description).

kindqueryRepoKind
ownerqueryHandle

Filter by owner handle (username or org slug).

tagqueryarray of Tag

Filter by tag; repeatable (AND semantics).

visibilityqueryVisibility
sortquerystring

one of updated · created

default "updated"

Sort key, always descending (newest first).

robotquerystring

length ≤ 129 · pattern ^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?/[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$

UI-API: owner/slug of a robot repo — only model repos whose model_meta.robot names it (the policies built for that robot), as part of the query, never a filter over a page. A robot repo the caller cannot see yields an empty page, exactly like an unknown owner: this filter is not an existence oracle.

interface_fingerprintquerystring

pattern ^[0-9a-f]{64}$

K2: only robot repos whose card's CURRENT interface_fingerprint is this — the robot a stamped policy was built for, found from the embodiment_fingerprint in its manifest. Part of the query, like every filter here.

facetsquerystring

one of tags

UIV2-thumbs — tags adds facets to the page: how many of the caller's visible repos carry each tag, counted in the query (visibility is a WHERE, never a post-filter, so a private repo never adds to a count a stranger sees). kind and owner scope the counted set; q, tag, visibility and robot do NOT, so a filter rail's counts hold still while you click (the rule of listRuns?facets=true). Omit it and nothing is counted.

limitqueryinteger

default 20 · ≥ 1 · ≤ 100

Page size.

cursorquerystring

length ≤ 512

Opaque cursor from the previous page's next_cursor.

Responses

listRepos responses
StatusDescriptionBody
200

Page of repos.

RepoPage
422

Request failed validation.

Problemapplication/problem+json

POST /v1/repos

Create a repo

createRepo · scope key:write

Creates a dataset, model or robot repo. owner defaults to the caller's username; pass an org slug to create under an org the caller belongs to. Visibility defaults to private.

Request body

application/json · required · RepoCreate

createRepo request body
FieldTypeDescription
kindrequiredRepoKind
slugrequiredSlug
ownerHandle | null

Owner handle; defaults to the caller's username.

visibilityVisibility

default "private"

descriptionstring | null

length ≤ 4096

tagsarray of Tag

items ≤ 20

Responses

createRepo responses
StatusDescriptionBody
201

Repo created.

Repo
401

Missing or invalid credentials.

Problemapplication/problem+json
403

Authenticated but not allowed (visibility, membership or scope).

Problemapplication/problem+json
409

State conflict (duplicate handle/slug, wrong repo kind, terminal job, ...).

Problemapplication/problem+json
422

Request failed validation.

Problemapplication/problem+json

GET /v1/repos/{owner}/{repo}

Get a repo

getRepo · scope none

Full repo detail including the kind-specific meta block (dataset_meta | model_meta | robot_card) when set.

Parameters

getRepo parameters
NameInTypeDescription
ownerrequiredpathHandle

Repo owner handle (username or org slug).

reporequiredpathSlug

Repo slug.

Responses

getRepo responses
StatusDescriptionBody
200

The repo.

Repo
404

Resource not found (or hidden from the caller).

Problemapplication/problem+json

PATCH /v1/repos/{owner}/{repo}

Update a repo

updateRepo · scope key:write

Updates description, tags and/or visibility. Slug rename is not supported in v0. Requires write access to the repo.

Parameters

updateRepo parameters
NameInTypeDescription
ownerrequiredpathHandle

Repo owner handle (username or org slug).

reporequiredpathSlug

Repo slug.

Request body

application/json · required · RepoUpdate

updateRepo request body
FieldTypeDescription
visibilityVisibility | null
descriptionstring | null

length ≤ 4096

tagsarray of Tag | null

items ≤ 20

Responses

updateRepo responses
StatusDescriptionBody
200

Updated repo.

Repo
401

Missing or invalid credentials.

Problemapplication/problem+json
403

Authenticated but not allowed (visibility, membership or scope).

Problemapplication/problem+json
404

Resource not found (or hidden from the caller).

Problemapplication/problem+json
422

Request failed validation.

Problemapplication/problem+json

DELETE /v1/repos/{owner}/{repo}

Delete a repo

deleteRepo · scope key:write

Deletes the repo and unlinks its files (content-addressed blobs are garbage-collected later). Requires write access. A repo referenced by training-run or rollout history cannot be deleted (409) — cost and provenance rows must survive. Archive/hide (retire a repo from listings without destroying history) is the v1+ escape hatch for that case.

Parameters

deleteRepo parameters
NameInTypeDescription
ownerrequiredpathHandle

Repo owner handle (username or org slug).

reporequiredpathSlug

Repo slug.

Responses

deleteRepo responses
StatusDescriptionBody
204

Repo deleted.

401

Missing or invalid credentials.

Problemapplication/problem+json
403

Authenticated but not allowed (visibility, membership or scope).

Problemapplication/problem+json
404

Resource not found (or hidden from the caller).

Problemapplication/problem+json

Schemas (33)

The schemas these operations reach before any other tag’s do. A type that links elsewhere is rendered on that tag’s page.

RepoKind

string

one of dataset · model · robot

Handle

string

length 1–64 · pattern ^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$

Owner handle — a username or org slug (shared namespace).

Tag

string

length 1–64 · pattern ^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$

Visibility

string

one of public · private

RepoPage

object

RepoPage fields
FieldTypeDescription
itemsrequiredarray of Repo
next_cursorrequiredstring | null
facetsRepoFacets | null

UIV2-thumbs — present only when listRepos?facets=tags.

RepoCreate

object

RepoCreate fields
FieldTypeDescription
kindrequiredRepoKind
slugrequiredSlug
ownerHandle | null

Owner handle; defaults to the caller's username.

visibilityVisibility

default "private"

descriptionstring | null

length ≤ 4096

tagsarray of Tag

items ≤ 20

Repo

object

Repo fields
FieldTypeDescription
idrequiredId
kindrequiredRepoKind
ownerrequiredRepoOwner
slugrequiredSlug
full_namerequiredstring

{owner}/{slug} — the canonical address.

visibilityrequiredVisibility
descriptionstring | null

length ≤ 4096

tagsrequiredarray of Tag

items ≤ 20

dataset_metaDatasetMeta | null

Present only when kind is dataset and meta has been set.

model_metaModelMeta | null

Present only when kind is model and meta has been set.

robot_cardRobotCard | null

Present only when kind is robot and a card has been set.

file_summaryRepoFileSummary
policy_countread-onlyinteger | null

≥ 0

UIV2-thumbs — on a robot repo, how many model repos name it as model_meta.robot and are visible to the caller, counted in one grouped query per page under the same visibility WHERE as listRepos (so it equals the number of repos listRepos?kind=model&robot={full_name} pages through, and never counts a private policy for a stranger). Null on dataset and model repos.

created_atrequiredstring (date-time)
updated_atrequiredstring (date-time)

RepoUpdate

object

All fields optional; omitted fields are unchanged.

RepoUpdate fields
FieldTypeDescription
visibilityVisibility | null
descriptionstring | null

length ≤ 4096

tagsarray of Tag | null

items ≤ 20

RepoFacets

object

UIV2-thumbs — counts over the caller's visible repos of the requested kind (and owner, when given); q, tag, visibility and robot are not applied, so the counts hold still while a filter changes.

RepoFacets fields
FieldTypeDescription
totalrequiredinteger

≥ 0

Every visible repo in the counted set (the "All" row).

tagsrequiredarray of RepoFacetBucket

items ≤ 100

One bucket per tag carried by at least one repo of the set, count descending then tag ascending; at most 100 (a rail does not print more). A repo counts once per tag.

RepoOwner

object

RepoOwner fields
FieldTypeDescription
typerequiredstring

one of user · org

idrequiredId
handlerequiredHandle

DatasetMeta

object

DatasetMeta fields
FieldTypeDescription
episode_countrequiredinteger

≥ 0

fpsnumber | null

> 0

robot_typestring | null

length ≤ 128

Free-form robot type label (e.g. laika, so101).

total_framesrequiredinteger

≥ 0

updated_atread-onlystring (date-time)

ModelMeta

object

ModelMeta fields
FieldTypeDescription
policy_typerequiredstring

length ≤ 128

Policy family (e.g. act, smolvla).

base_modelstring | null

length ≤ 256

Base model reference when finetuned.

source_run_idstring | null

Training run (run_...) that produced this model, if trained on the hub.

control_classControlClass | null

Which layer the policy belongs to (M15). Null means undeclared — such a model cannot become an endpoint until it says.

robotstring | null

UI-API: owner/slug of the robot repo the policy was built for. Null when none was recorded — or when that robot repo is not visible to the caller, so a public policy never names a private robot.

embodiment_fingerprintstring | null

pattern ^[0-9a-f]{64}$

UI-API: the embodiment-interface fingerprint recorded in the policy's manifest (M17b stamps it): the interface_fingerprint of the robot card the policy was trained against. Null for a policy whose manifest records none — every policy published before M17b.

embodiment_checkread-onlyEmbodimentCheck | null

UI-API: embodiment_fingerprint against the recorded robot's CURRENT interface_fingerprint, computed on read. Null when no robot is recorded or it is not visible to the caller.

updated_atread-onlystring (date-time)

RobotCard

object

RobotCard fields
FieldTypeDescription
dofrequiredinteger

≥ 0

actuatorsrequiredarray of Actuator
mass_kgnumber | null

> 0

limitsmap of JointLimits | null

Map of joint name → limits.

mjcf_pathFilePath | null

Repo-relative path of the MJCF file inside this repo.

description_mdstring | null

length ≤ 65536

Markdown notes rendered on the robot page.

interfaceEmbodimentInterface | null

The embodiment interface (M17): the robot-side declaration every training, sim-gate and deploy path reads. Null on a card that only describes the hardware.

interface_fingerprintread-onlystring | null

pattern ^[0-9a-f]{64}$

sha256 of the canonical interface JSON — the index space a policy or a dataset is built for. Null when interface is.

validationRobotValidationRecord | null

UI2: the last validation report stored with the card, as the publisher sent it. Null when none was sent.

thumbnail_pathsRobotThumbnailPaths | null

UIV2-thumbs: the robot's still, one per theme, as repo files — fetch them through the repo's raw route (presigned on request). Null when the publisher rendered none (no GL on its machine, or --no-thumbnail).

updated_atread-onlystring (date-time)

RepoFileSummary

object

UI2: what the repo holds, computed on read (one grouped query per page): how many files, their bytes, and how many of their blobs the hub has hashed itself (M3 verified). A repo page prints 26 · 30,882,681 B and "digests all verified by the hub" from this instead of walking the tree.

RepoFileSummary fields
FieldTypeDescription
countrequiredinteger

≥ 0

total_bytesrequiredinteger

≥ 0

verified_countrequiredinteger

≥ 0

Files whose blob is verified; equal to count means every digest is proven.

RepoFacetBucket

object

RepoFacetBucket fields
FieldTypeDescription
valuerequiredstring

The tag; listRepos?tag={value} selects exactly these repos.

countrequiredinteger

≥ 0

ControlClass

string

one of reflex · skill · planner

Which layer of the robot stack a model belongs to (M15, docs/ARCHITECTURE.md "Inference placement"). reflex — a 50 Hz+ stabilisation / locomotion policy that must run on the robot and is never served over a network by this hub (createEndpoint on one is 409); skill — a VLA / skill policy emitting action chunks at 1–10 Hz, servable as an endpoint; planner — a task-level model at ~1 Hz, servable as an endpoint. The importer and the runner set reflex for every Lucen legged policy and for stub_ppo.

EmbodimentCheck

string

one of match · mismatch · policy_unstamped · robot_undeclared

How a policy's recorded embodiment fingerprint compares with a robot's current interface fingerprint — the device driver's vocabulary (M17d), where mismatch is its embodiment_mismatch refusal. match — the same interface; mismatch — the robot's interface changed since the policy was built, or the policy was built for another one; policy_unstamped — the policy records no fingerprint; robot_undeclared — the robot card declares no interface.

Actuator

object

One actuator group; extra vendor-specific fields allowed.

Actuator fields
FieldTypeDescription
namerequiredstring

length ≤ 128

modelstring | null

length ≤ 128

countinteger | null

≥ 1

JointLimits

object

Per-joint limits; units are SI (rad, rad/s, N·m).

JointLimits fields
FieldTypeDescription
lowernumber | null
uppernumber | null
velocitynumber | null
effortnumber | null

FilePath

string

length 1–1024

Repo-relative file path with / separators. No leading /, no . or .. segments (server-enforced).

EmbodimentInterface

object

What a robot IS to a policy, declared once: the canonical joint order (the policy's index space), base type, default pose, how the joints are driven, what an action means, the control rate, which proprioception the real robot has, named parts, end effectors, cameras, what a person or planner commands, and the safe-stop behaviour. None of it is carried by a URDF/MJCF, and a wrong value of any of it fails silently at deploy time. Poses, actuator groups, parts and per-joint scales may only name joints in joint_order, and no joint may be driven by two actuator groups.

EmbodimentInterface fields
FieldTypeDescription
versionrequiredinteger

one of 1

baserequiredstring

one of fixed · floating

joint_orderrequiredarray of string

items 1–64 · unique items

Joint names in policy index order. Hashed; never reorder silently.

default_posemap of number | null

Joint name → position (rad or m) the robot starts from and offsets are relative to.

default_keyframestring | null

length ≤ 128

Name of the MJCF keyframe holding the default pose, if there is one.

init_base_height_mnumber | null

> 0

Floating base only.

control_rate_hzrequirednumber

> 0 · ≤ 2000

physics_dt_snumber | null

> 0 · ≤ 0.1

actuationarray of EmbodimentActuation

items ≤ 64

actionrequiredEmbodimentAction
proprioceptionarray of string

items ≤ 32 · unique items

Observation terms the REAL robot can supply (joint_pos, joint_vel, base_ang_vel, projected_gravity, foot_contact, ee_pos, …). A policy's observations must be a subset.

partsarray of EmbodimentPart

items ≤ 16

end_effectorsarray of EmbodimentEndEffector

items ≤ 8

feetarray of string

items ≤ 8

Bodies or sites that touch the ground (legged robots).

camerasarray of EmbodimentCamera

items ≤ 8

command_spaceEmbodimentCommandSpace
safetyEmbodimentSafety

RobotValidationRecord

object

UI2: the last lucen robot validate report, stored WITH the card by lucen robot publish (or sent by hand on putRobotCard) so a robot page can print 14 pass · 2 warn · 0 fail and each warning without re-running anything. The hub never runs MuJoCo, so a mujoco record is the publisher's claim about the files at checked_at, not a verdict of the hub's: the hub's own static checks still run on every putRobotCard and refuse the card regardless of what the record says. checked_at older than the card's updated_at means the card changed since it was checked.

RobotValidationRecord fields
FieldTypeDescription
enginerequiredstring

one of static · mujoco

engine_versionstring | null

length ≤ 64

mujoco.__version__ for a mujoco record; null for static.

checked_atrequiredstring (date-time)
checksrequiredarray of RobotValidationCheck

items ≤ 128

check_idstring | null

length ≤ 64

R1: the hosted check (rchk_…) this report came from, set by publishRobotCheck. The card was published exactly as that check drafted and hashed it, however long after checked_at the person pressed Publish — so a page reads the record as current rather than dating it against the card's updated_at. Still the publisher's claim, like every other field here.

RobotThumbnailPaths

object

UIV2-thumbs — the robot drawn at its default pose by MuJoCo's own offscreen renderer on the publisher's machine (the hub never runs MuJoCo), 640×480, framed on the robot's geoms, one image per theme: light on the light panel colour with a faint grid, dark on the dark one. A still is the publisher's picture of the files it pushed, like validation is its report.

RobotThumbnailPaths fields
FieldTypeDescription
lightrequiredFilePath
darkrequiredFilePath
render_keystring | null

pattern ^[0-9a-f]{64}$

sha256 over what the stills were rendered from (the renderer's version, MuJoCo's, every file the MJCF reads and the pose the card declares). lucen robot publish renders again only when it changes, so re-publishing an unchanged robot uploads nothing on any machine. Null for stills the publisher did not render (a photo).

EmbodimentActuation

object

EmbodimentActuation fields
FieldTypeDescription
jointsrequiredarray of string

items 1–64

modestring

one of position · velocity · torque

default "position"

kpnumber | null

≥ 0

kdnumber | null

≥ 0

effort_limitnumber | null

> 0

velocity_limitnumber | null

> 0

armaturenumber | null

≥ 0

friction_lossnumber | null

≥ 0

delay_msnumber | null

≥ 0 · ≤ 1000

EmbodimentAction

object

EmbodimentAction fields
FieldTypeDescription
semanticsrequiredstring

one of position_offset · position_absolute · velocity · torque

position_offset is relative to default_pose.

scalenumber

default 1 · > 0

scale_per_jointmap of number | null

Overrides scale for the joints it names.

clipnumber | null

> 0

EmbodimentPart

object

EmbodimentPart fields
FieldTypeDescription
namerequiredstring

length 1–64

kindstring

one of leg · arm · gripper · base · head · torso · other

default "other"

jointsrequiredarray of string

items 1–64

EmbodimentEndEffector

object

EmbodimentEndEffector fields
FieldTypeDescription
namerequiredstring

length 1–64

sitestring | null

length ≤ 128

bodystring | null

length ≤ 128

gripper_jointstring | null

length ≤ 128

in_mjcfboolean

default true

False for a real tool the model does not contain.

EmbodimentCamera

object

EmbodimentCamera fields
FieldTypeDescription
namerequiredstring

length 1–64

mountstring | null

length ≤ 128

widthinteger | null

≥ 1 · ≤ 8192

heightinteger | null

≥ 1 · ≤ 8192

fpsnumber | null

> 0 · ≤ 1000

vla_slotEmbodimentCameraSlot | null

Which image slot of a VLA this camera feeds.

EmbodimentCommandSpace

object

EmbodimentCommandSpace fields
FieldTypeDescription
kindstring

one of none · velocity2d · joint_target · ee_target

default "none"

The morphology hint generic task templates key on.

rangesmap of array of number | null

Command name → [lower, upper].

EmbodimentSafety

object

EmbodimentSafety fields
FieldTypeDescription
soft_limit_factornumber

default 0.95 · > 0 · ≤ 1

max_tilt_radnumber | null

> 0

safe_stopstring

one of hold · zero_torque · default_pose

default "hold"

RobotValidationCheck

object

One check. code is stable and machine-readable (mjcf.exists, mjcf.parses, assets.closure, interface.joint_order, interface.base, … — the full list is in docs/API.md); names are the offending joints, files or fields; hint is a one-line fix.

RobotValidationCheck fields
FieldTypeDescription
coderequiredstring

length ≤ 64 · pattern ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$

statusrequiredRobotCheckStatus
messagerequiredstring

length ≤ 2000

namesarray of string

items ≤ 256

hintstring | null

length ≤ 1000

locarray of string | integer | null

Path into the card body the check is about, when there is one.

dataobject | null

Numbers behind the verdict (drift, penetration, counts), per check.

EmbodimentCameraSlot

string

one of base · wrist_left · wrist_right · other

RobotCheckStatus

string

one of pass · warn · fail · skip

fail blocks putRobotCard (422) and lucen robot publish; warn never blocks; skip means the check could not run and says why (usually because an earlier one failed).