API reference

Every operation in docs/openapi.yaml, with its auth scope. The contract is the source of truth for all four surfaces.

Download openapi.yamlOpenAPI 3.1 · version 0.1.0 · 150 operations · 485 schemas

Rendered from the contract at build time — the same file make sdk generates both clients from, so nothing here can drift from it. The CLI, the MCP server and the generated SDKs are the clients; this page is the reference.

The open hub for robot data, models and training. One REST API serving the web app, CLI, MCP server and generated SDKs.

Conventions

IDs — every resource has a stable, prefixed, lexicographically sortable id: {prefix}_{26-char Crockford-base32 ULID} (e.g. repo_01J8ZC9EXAMPLE0000000000EX). Prefixes: user_, org_, member_, key_, repo_, file_, run_, rollout_, audit_, ledger_, and from M13 dev_, dreq_, appr_, devt_, from M15 ep_, esess_, and from R1 rchk_. Repos are addressed in URLs by {owner}/{repo} (handles), jobs by id. Pagination — cursor-based everywhere: pass limit and the opaque cursor from the previous page; responses are {items: [...], next_cursor: string|null}. next_cursor: null means exhausted. Cursors are opaque; do not construct them. Errors — RFC 9457 application/problem+json: {type, title, status, detail?, instance?, errors?}. Validation failures use status 422 with per-field errors[]. Auth — Authorization: Bearer <token> where the token is either a Clerk session JWT (web) or a scoped API key lucen_sk_... (CLI/MCP/SDK). Scopes are a strict hierarchy — read ⊂ write ⊂ train: key:read (read + download) < key:write (all data mutations: repos, files, meta, orgs) < key:train (compute and money: submit training runs and rollouts; implies write). Splitting data from money is deliberate — an agent-held key can be allowed to browse and push data while being unable to spend GPU dollars. A session token carries the user's full powers. Every operation declares its minimum programmatic scope in x-auth-scope (none | key:read | key:write | key:train | session); none means anonymous works for public resources — private resources still require auth + access. session means no API key is ever sufficient: only a Clerk session may call it. Two families are session in v0: API key management, so that a leaked write-scoped agent key cannot mint itself a train-scoped one, and device approvals (M13), so that no key of any scope — and therefore no agent — can put a policy on a robot; an agent may only request one.

Visibility — private resources are invisible, not merely forbidden: a caller without access gets 404, never 403, on read paths (a 403 would confirm the resource exists). 403 is reserved for a caller who can see the resource but lacks the scope or membership to act on it.

Rate limits — anonymous, per client IP: 300 requests/minute for a credential-less GET/HEAD (a page view is several reads) and 60/minute for everything else (unsafe methods, and any request whose credential failed to verify); 600/minute authenticated (per session user or per API key). Every /v1 response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (unix seconds); exceeding the limit yields 429 with Retry-After and a problem body. 429 is an infrastructure response and is therefore not enumerated per operation. Timestamps — RFC 3339 UTC (2026-08-31T12:00:00Z).

Auth scopes

Each operation declares one, as the x-auth-scope extension in the spec. A test asserts the spec and the scope table in docs/API.md agree in both directions, so neither can rot.

Auth scopes
Scope	What it gates
none	Anonymous. Public repos, episodes, and the Coach corpus.
key:read	List and read what the credential's owner can see.
key:write	Create repos, upload files, import a run. Implies read.
key:train	Spend money: GPU jobs, Coach advice. Implies write.
session	Browser session only. Key management and device approvals — no API key may mint another, and no key may put a policy on a robot.

Every operation (150)

Grouped by tag, in the contract’s order. Each path opens the operation’s section: parameters, request body, responses.

meta (1)

Service metadata and probes

meta operations
Method	Path	Scope	Summary
GET	/healthzhealthz	none	Liveness probe

install (1)

K3 — the hub's own installer for its clients (lucen, lucen-device, lucen-mcp)

install operations
Method	Path	Scope	Summary
GET	/install.shgetInstallScript	none	The installer for this hub's clients

auth (1)

Identity of the caller

auth operations
Method	Path	Scope	Summary
GET	/v1/auth/megetMe	key:read	Who am I

keys (3)

Scoped API keys for programmatic access (CLI / MCP / SDK)

keys operations
Method	Path	Scope	Summary
GET	/v1/keyslistApiKeys	session	List my API keys
POST	/v1/keyscreateApiKey	session	Create an API key
DELETE	/v1/keys/{key_id}revokeApiKey	session	Revoke an API key

users (1)

Public user profiles

users operations
Method	Path	Scope	Summary
GET	/v1/users/{username}getUser	none	Public user profile

orgs (7)

Organizations and membership (CRUD-lite)

orgs operations
Method	Path	Scope	Summary
GET	/v1/orgslistMyOrgs	key:read	List my organizations
POST	/v1/orgscreateOrg	key:write	Create an organization
GET	/v1/orgs/{org}getOrg	none	Get an organization
PATCH	/v1/orgs/{org}updateOrg	key:write	Update an organization
GET	/v1/orgs/{org}/memberslistOrgMembers	key:read	List organization members
PUT	/v1/orgs/{org}/members/{username}putOrgMember	key:write	Add or update a member
DELETE	/v1/orgs/{org}/members/{username}removeOrgMember	key:write	Remove a member

repos (5)

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

repos operations
Method	Path	Scope	Summary
GET	/v1/reposlistRepos	none	List / search repos
POST	/v1/reposcreateRepo	key:write	Create a repo
GET	/v1/repos/{owner}/{repo}getRepo	none	Get a repo
PATCH	/v1/repos/{owner}/{repo}updateRepo	key:write	Update a repo
DELETE	/v1/repos/{owner}/{repo}deleteRepo	key:write	Delete a repo

files (5)

Repo files — presigned multipart upload/download against object storage, tree listing

files operations
Method	Path	Scope	Summary
GET	/v1/repos/{owner}/{repo}/treegetRepoTree	none	List repo files
POST	/v1/repos/{owner}/{repo}/files/presign-uploadpresignUpload	key:write	Presign a batch multipart upload
POST	/v1/repos/{owner}/{repo}/files/completecompleteUpload	key:write	Complete a batch multipart upload
POST	/v1/repos/{owner}/{repo}/files/presign-downloadpresignDownload	none	Presign downloads
POST	/v1/repos/{owner}/{repo}/files/deletedeleteFiles	key:write	Delete files (batch unlink)

datasets (4)

Dataset-kind repo extras — episode index, frames index, per-episode playback payload, dataset meta

datasets operations
Method	Path	Scope	Summary
GET	/v1/datasets/{owner}/{repo}/episodeslistDatasetEpisodes	none	List dataset episodes
GET	/v1/datasets/{owner}/{repo}/episodes/{episode_index}/frames-indexgetEpisodeFramesIndex	none	Frames index for one episode
GET	/v1/datasets/{owner}/{repo}/episodes/{episode_index}/seriesgetEpisodeSeries	none	Playable payload for one episode
PUT	/v1/datasets/{owner}/{repo}/metaputDatasetMeta	key:write	Set dataset meta

models (1)

Model-kind repo extras — model meta

models operations
Method	Path	Scope	Summary
PUT	/v1/models/{owner}/{repo}/metaputModelMeta	key:write	Set model meta

robots (11)

Robot-kind repo extras — robot card

robots operations
Method	Path	Scope	Summary
GET	/v1/robots/{owner}/{repo}/cardgetRobotCard	none	Get a robot card
PUT	/v1/robots/{owner}/{repo}/cardputRobotCard	key:write	Set a robot card
POST	/v1/robots/{owner}/{repo}/validatevalidateRobot	key:read	Validate a robot card against the repo's MJCF, without writing
GET	/v1/robot-checkslistRobotChecks	key:read	List hosted robot checks
POST	/v1/robot-checkscreateRobotCheck	key:write	Queue a hosted check of a robot repo's model
GET	/v1/robot-checks/{check_id}getRobotCheck	key:read	Get a hosted robot check
POST	/v1/robot-checks/{check_id}/claimclaimRobotCheck	key:write	Claim a queued check (robot check worker protocol)
POST	/v1/robot-checks/{check_id}/artifactspresignRobotCheckArtifacts	key:write	Presign uploads for a running check's artifacts
POST	/v1/robot-checks/{check_id}/reportreportRobotCheck	key:write	Report progress or the result of a claimed check
POST	/v1/robot-checks/{check_id}/publishpublishRobotCheck	key:write	Publish a check's draft card into the robot repo, as the caller
POST	/v1/robot-checks/{check_id}/cancelcancelRobotCheck	key:write	Cancel a hosted robot check

runs (14)

Training runs — submitted here, executed by an executor: a self-hosted worker (M7-RL) or Modal (modal, not built yet)

runs operations
Method	Path	Scope	Summary
GET	/v1/runslistRuns	key:read	List training runs
POST	/v1/runscreateRun	key:train	Create a training run
POST	/v1/runs/importimportRun	key:write	Import a training run trained off-platform
POST	/v1/runs/estimateestimateRun	key:train	Price a training run before submitting it
POST	/v1/runs/recommendrecommendRun	key:read	Recommend a GPU tier for a training run (deterministic planner)
GET	/v1/runs/{run_id}getRun	key:read	Get a training run
GET	/v1/runs/{run_id}/logsstreamRunLogs	key:read	Stream run logs (SSE)
GET	/v1/runs/{run_id}/logs/downloaddownloadRunLogs	key:read	Download a run's whole log as text
POST	/v1/runs/{run_id}/cancelcancelRun	key:train	Cancel a training run
GET	/v1/runs/{run_id}/configgetRunConfig	key:read	A run's resolved config, flattened, and its diff against the parent
GET	/v1/runs/{run_id}/checkpointslistRunCheckpoints	key:read	List a run's checkpoints
POST	/v1/runs/{run_id}/claimclaimRun	key:train	Claim a queued worker run (self-hosted runner protocol)
POST	/v1/runs/{run_id}/reportreportRun	key:train	Report progress or a terminal state for a claimed run
GET	/v1/hardware_tierslistHardwareTiers	none	GPU tiers and what an hour on each costs

rollouts (11)

Sim rollout jobs — watch a policy run in MuJoCo

rollouts operations
Method	Path	Scope	Summary
GET	/v1/rolloutslistRollouts	key:read	List sim rollouts
POST	/v1/rolloutscreateRollout	key:train	Create a sim rollout
GET	/v1/rollouts/{rollout_id}getRollout	key:read	Get a sim rollout
POST	/v1/rollouts/{rollout_id}/claimclaimRollout	key:train	Claim a queued rollout (rollout worker protocol)
POST	/v1/rollouts/{rollout_id}/artifactspresignRolloutArtifacts	key:train	Presign uploads for a running rollout's artifacts
POST	/v1/rollouts/{rollout_id}/reportreportRollout	key:train	Report progress or the result of a claimed rollout
POST	/v1/rollouts/{rollout_id}/cancelcancelRollout	key:train	Cancel a sim rollout
POST	/v1/rollouts/{rollout_id}/renderrenderRollout	key:train	Render an earlier rollout's videos
GET	/v1/runs/{run_id}/gatesgetRunGates	key:read	The sim gates a run's checkpoints got while it trained
GET	/v1/runs/{run_id}/scangetRunScan	key:read	A band scan's table
POST	/v1/runs/{run_id}/scanscanRun	key:train	Band-scan a run's checkpoints in simulation

devices (23)

Device consent layer (M13) — robot-side runners, approval requests an agent may make, approvals only a human session may sign, and the driver's telemetry summaries. No API key can put a policy on a robot.

devices operations
Method	Path	Scope	Summary
GET	/v1/devices/signing-keygetDeviceSigningKey	none	The hub's approval verification key
GET	/v1/deviceslistDevices	key:read	List devices
POST	/v1/devicesregisterDevice	key:write	Register a robot-side runner
POST	/v1/device-pairingscreateDevicePairing	key:write	Start pairing a robot from the platform
POST	/v1/device-pairings/claimclaimDevicePairing	none	Declare this robot to a pairing — with a code, or to get one
GET	/v1/device-pairings/{pairing}getDevicePairing	key:read	Get a pairing — has the robot joined, what did it declare?
DELETE	/v1/device-pairings/{pairing}rejectDevicePairing	key:write	Drop a pairing — "Not my robot"
POST	/v1/device-pairings/{pairing}/confirmconfirmDevicePairing	session	Confirm the robot that claimed a pairing (web session only)
POST	/v1/device-pairings/{pairing_id}/collectcollectDevicePairing	none	The robot picks up what a person confirmed
GET	/v1/devices/{device_id}getDevice	key:read	Get a device
POST	/v1/devices/{device_id}/disconnectdisconnectDevice	key:write	Disconnect a device — revoke its credential
POST	/v1/devices/{device_id}/trust-modesetDeviceTrustMode	key:write	The robot changes its own trust mode
GET	/v1/devices/{device_id}/approval-requestslistApprovalRequests	key:read	List a device's approval requests
POST	/v1/devices/{device_id}/approval-requestscreateApprovalRequest	key:write	Ask for a policy to be put on a device
GET	/v1/devices/{device_id}/approval-requests/{request_id}getApprovalRequest	key:read	Get an approval request
POST	/v1/devices/{device_id}/approval-requests/{request_id}/denydenyApprovalRequest	session	Deny an approval request (web session only)
GET	/v1/devices/{device_id}/approvalslistApprovals	key:read	List a device's approvals
POST	/v1/devices/{device_id}/approvalscreateApproval	session	Approve a pending request and mint the signed token (web session only)
GET	/v1/devices/{device_id}/approvals/{approval_id}getApproval	key:read	Get an approval
POST	/v1/devices/{device_id}/approvals/{approval_id}/stopstopApproval	key:write	Stop an approval now
GET	/v1/devices/{device_id}/eventslistDeviceEvents	key:read	List a device's events
POST	/v1/devices/{device_id}/eventspostDeviceEvent	key:write	Record a telemetry summary from the driver
GET	/v1/approval-requests/{request_id}getApprovalRequestById	key:read	Get an approval request by its id alone

endpoints (10)

Inference endpoints (M15) — hub-served inference for the skill / planner layer, never the reflex layer. Claimed by lucen serve, consumed by a device only through a signed approval bound to device + model digest + endpoint id, metered per session.

endpoints operations
Method	Path	Scope	Summary
GET	/v1/endpointslistEndpoints	key:read	List inference endpoints
POST	/v1/endpointscreateEndpoint	key:train	Create an inference endpoint for a skill-layer model
POST	/v1/endpoints/estimateestimateEndpoint	key:train	Price an endpoint before creating it
GET	/v1/endpoints/{endpoint_id}getEndpoint	key:read	Get an inference endpoint
DELETE	/v1/endpoints/{endpoint_id}stopEndpoint	key:train	Stop an inference endpoint
POST	/v1/endpoints/{endpoint_id}/claimclaimEndpoint	key:train	Claim a queued worker endpoint (`lucen serve` protocol)
POST	/v1/endpoints/{endpoint_id}/reportreportEndpoint	key:train	Report sessions, metering and state for a claimed endpoint
GET	/v1/endpoints/{endpoint_id}/sessionslistEndpointSessions	key:read	List an endpoint's sessions (metering)
POST	/v1/endpoints/{endpoint_id}/sessionsopenEndpointSession	key:write	Open a session on an endpoint (a device, with a human's approval)
POST	/v1/endpoints/{endpoint_id}/sessions/{session_id}/reportreportEndpointSession	key:write	The device's own metering for a session

coach (8)

Training Coach — the experience corpus, run diagnosis with in-whitelist proposals, and programme planning. Every claim cites a card.

coach operations
Method	Path	Scope	Summary
GET	/v1/coach/doctrinegetCoachDoctrine	none	The coach's doctrine (numbered methodology rules)
GET	/v1/coach/cardssearchExperienceCards	none	Search the experience corpus
GET	/v1/coach/cards/{card_id}getExperienceCard	none	Get one experience card
POST	/v1/coach/advicecreateAdvice	key:train	Diagnose a training run
POST	/v1/coach/plancreateCoachPlan	key:train	Plan a training programme from a task brief
GET	/v1/coach/sessionslistAdviceSessions	key:read	List coach sessions
GET	/v1/coach/sessions/{session_id}getAdviceSession	key:read	Get a coach session
POST	/v1/coach/sessions/{session_id}/feedbacksetAdviceFeedback	key:write	Rate a coach report

plans (5)

The planner (M16) — a frontier model orchestrates the three layers for one task on one device through a closed step vocabulary; it can only request approvals (a human signs them), never opens a session, never names a joint. Recorded as an orchestration run.

plans operations
Method	Path	Scope	Summary
GET	/v1/planslistPlans	key:read	List plans
POST	/v1/planscreatePlan	key:train	Plan a task for a robot (the planner makes its first decision)
GET	/v1/plans/{plan_id}getPlan	key:read	Get a plan (steps, timeline, what it is waiting on)
POST	/v1/plans/{plan_id}/advanceadvancePlan	key:train	Run one orchestrator tick on a plan (idempotent)
POST	/v1/plans/{plan_id}/cancelcancelPlan	key:train	Cancel a plan

campaigns (9)

Campaigns (C3) — the founder's training loop as hub objects: a task on a robot with a budget, whose rounds lock a spec (one declared change, a hypothesis, gates with predictions), train through createRun, are gated and band-scanned in simulation, get a verdict from their locked gates and a decision. Three rules are enforced in code; only a signed-in person may override one, with a reason.

campaigns operations
Method	Path	Scope	Summary
GET	/v1/campaignslistCampaigns	key:read	List campaigns
POST	/v1/campaignscreateCampaign	key:write	Start a campaign — a task on a robot, with a budget and the three rules
GET	/v1/campaigns/{campaign_id}getCampaign	key:read	Get a campaign (its rounds, spend, and what waits on a person)
PATCH	/v1/campaigns/{campaign_id}updateCampaign	key:write	Rename, re-describe, change the budget of, or stop a campaign
POST	/v1/campaigns/{campaign_id}/roundscreateRound	key:train	Lock a round's spec and start its training run
POST	/v1/campaigns/{campaign_id}/rounds/overridecreateRoundWithOverride	session	Start a round that breaks a rule — a person's decision, with a reason
GET	/v1/campaigns/{campaign_id}/rounds/{round_n}getRound	key:read	Get a round — its locked spec, the verdict at a step, the variables, the decisions
POST	/v1/campaigns/{campaign_id}/rounds/{round_n}/decisiondecideRound	key:write	Decide a round — shortlist, iterate, stop the lineage, or done
POST	/v1/campaigns/{campaign_id}/rounds/{round_n}/gatesaddRoundGate	key:write	Add a gate after the lock — shown, never counted

trials (14)

Real-robot trials (C4) — a session of trials on one device, each a checkpoint run under its own M13 approval with a run sheet locked at approval, the log and summary the driver uploads signed with the device key, the operator's notes from a phone, and a person's verdict (promote / iterate / stop) that the campaign's rules read.

trials operations
Method	Path	Scope	Summary
GET	/v1/trial-sessionslistTrialSessions	key:read	List real-robot sessions
POST	/v1/trial-sessionscreateTrialSession	key:write	Plan a real-robot session — one trial per checkpoint, in bracket order
GET	/v1/trial-sessions/{session_id}getTrialSession	key:read	Get a real-robot session — its order, bracket check and trials
POST	/v1/trial-sessions/{session_id}/requestsfileTrialRequests	key:write	File the consent requests of a session's unfiled trials
GET	/v1/trialslistTrials	key:read	List trials
GET	/v1/trials/{trial_id}getTrial	key:read	Get a trial — run sheet, approval, log, summary, criteria, notes, verdict
PATCH	/v1/trials/{trial_id}/run-sheetupdateTrialRunSheet	key:write	Edit a trial's run sheet before its approval locks it
POST	/v1/trials/{trial_id}/log/presignpresignTrialLog	key:write	Presigned PUTs for the log files a driver will upload
POST	/v1/trials/{trial_id}/loguploadTrialLog	key:write	Record the log and summary the driver computed on the robot, signed
GET	/v1/trials/{trial_id}/seriesgetTrialSeries	key:read	The log as plottable series — tilt at 50 Hz, joints on request
PATCH	/v1/trials/{trial_id}/notesputTrialNotes	key:write	Save the operator's notes — a partial autosave
POST	/v1/trials/{trial_id}/notes/videospresignTrialVideo	key:write	Start a phone video's presigned multipart upload
POST	/v1/trials/{trial_id}/notes/videos/{video_id}/completecompleteTrialVideo	key:write	Finish a phone video's upload and attach it to the notes
POST	/v1/trials/{trial_id}/verdictsetTrialVerdict	session	Record a person's verdict on a candidate trial (web session only)

workspace (2)

The signed-in caller's workspace (UI-API) — the activity feed (the audit log, filtered to what the caller could already see) and one cheap overview for the workspace rail and the Inbox header.

workspace operations
Method	Path	Scope	Summary
GET	/v1/activitylistActivity	key:read	The activity feed — what happened to what you can see
GET	/v1/me/overviewgetMyOverview	key:read	Counts for the workspace rail and the Inbox header

agent (14)

The hub's cloud agent (A1/A2) — a session works toward a goal with the hub's own tools and a sandboxed shell, as a short-lived key scoped below its creator's; spends past a pre-approved budget wait for a person, and everything it does is an append-only event stream.

agent operations
Method	Path	Scope	Summary
GET	/v1/agent/sessionslistAgentSessions	key:read	List agent sessions
POST	/v1/agent/sessionscreateAgentSession	key:train	Start an agent session (the hub's cloud agent works toward a goal)
GET	/v1/agent/sessions/{session_id}getAgentSession	key:read	Get an agent session (status, spend, what it waits on, pending approvals)
POST	/v1/agent/sessions/{session_id}/messagespostAgentMessage	key:train	Send the agent a message (a user turn)
GET	/v1/agent/sessions/{session_id}/eventsstreamAgentEvents	key:read	Stream a session's events (SSE, resumable)
POST	/v1/agent/sessions/{session_id}/approvals/{approval_id}resolveAgentApproval	key:train	Approve or deny a spend the agent asked for
POST	/v1/agent/sessions/{session_id}/cancelcancelAgentSession	key:train	Cancel an agent session
POST	/v1/agent/sessions/{session_id}/endendAgentSession	key:train	End an agent session (done; a reply reopens it)
GET	/v1/agent/sessions/{session_id}/planslistAgentPlans	key:read	The plans the agent proposed in this session, newest version first
GET	/v1/agent/sessions/{session_id}/plans/{plan_id}getAgentPlan	key:read	One version of the session's plan
POST	/v1/agent/sessions/{session_id}/plans/{plan_id}/approveapproveAgentPlan	session	Approve the agent's plan (a signed-in person only)
GET	/v1/agent/sessions/{session_id}/decisionslistAgentDecisions	key:read	The session's decisions — plan, spend, shortlist, handoff
GET	/v1/agent/sessions/{session_id}/digestgetAgentDigest	key:read	"Since you left" — what happened in the session since the viewer last looked
GET	/v1/agent/sessions/{session_id}/objectslistAgentObjects	key:read	The session's objects grouped by state — Needs you, Running, Ready for review, Done

Errors

The response families the operations share. Every error body is RFC 9457 application/problem+json; 429 is an infrastructure response and is not listed per operation.

Shared error responses
Response	Description	Body
`Unauthorized`	Missing or invalid credentials.	`Problem`application/problem+json
`Forbidden`	Authenticated but not allowed (visibility, membership or scope).	`Problem`application/problem+json
`NotFound`	Resource not found (or hidden from the caller).	`Problem`application/problem+json
`Conflict`	State conflict (duplicate handle/slug, wrong repo kind, terminal job, ...).	`Problem`application/problem+json
`ValidationError`	Request failed validation.	`Problem`application/problem+json
`ServiceUnavailable`	A service this endpoint needs is not configured in this deployment (M0's boot guarantee: the API boots with zero secrets, and an endpoint that needs one says so instead of returning a stack trace).	`Problem`application/problem+json

Common schemas

What the shared responses carry. Every other schema is on the page of the first tag whose operations use it.

Problem

object

RFC 9457 problem details. Served as application/problem+json.

Problem fields
Field	Type	Description
`type`	`string` default `"about:blank"`	URI reference identifying the problem type.
`title`required	`string`	Short human-readable summary of the problem type.
`status`required	`integer` ≥ `100` · ≤ `599`
`detail`	`string \| null`	Human-readable explanation specific to this occurrence.
`instance`	`string \| null`	URI reference identifying this occurrence.
`errors`	`array of FieldError \| null`	Field-level validation errors (422 responses).

FieldError