Skip to content
Qualia Docs

Versions_StartMaterialization

POST
/v1/accounts/{account}/datasets/{dataset}/versions/{version}/materializations/{materialization}:start
 
curl --request POST \
  --url https://junction-api.qualiastudios.dev/v1/accounts/example/datasets/example/versions/example/materializations/example:start \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "name": "example" }'

Starts rendering a tag in the id’s layout, or picks up the rendering already there: it never renders twice. Answers at once; read the materialization again until SUCCEEDED, then list its artifacts. FAILED_PRECONDITION for head (tag it first) and when the rendering failed for good (the message says why); UNAVAILABLE when the renderer cannot be reached (retry).

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
account
required
string

The account id.

dataset
required
string

The dataset id.

version
required
string

The version id.

materialization
required
string

The materialization id.

Request Body required

Section titled “Request Body required ”
Media type application/json

Request for Versions.StartMaterialization.

object
name
required

Accounts/{account}/datasets/{dataset}/versions/{version}/materializations/{materialization}: a tag, stable or a digest prefix, and the layout.

string
Example generated
{
  "name": "example"
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

OK

Media type application/json

A tag rendered as a LeRobot or MCAP ROS2 dataset, to download. The files stay in object storage: each artifact carries a short-lived signed URI to its immutable object, never the bytes. Rendering runs in the background: StartMaterialization begins it, and every later call, from anyone, finds the same rendering. A tag never moves, so the same tag rendered by the same renderer gives the same files, byte for byte.

The {materialization} id is the layout: lerobot-v3 (LeRobot v3.0), lerobot-v2-1 (LeRobot v2.1) or mcap-ros2 (one ROS 2 MCAP file per episode). head is not pinned, so it has none: tag it first.

Served by qds-api.

object
name

Accounts/{account}/datasets/{dataset}/versions/{version}/materializations/{materialization}. The version segment is the tag, also when the request named stable or a digest prefix.

string
state

How far the rendering is.

string format: enum
Allowed values: STATE_UNSPECIFIED NOT_STARTED RUNNING SUCCEEDED INTERRUPTED
digest

“b3:”, once SUCCEEDED: one hash over every artifact’s path and content, so two renderings with one digest are the same files.

string
artifactCount

Files in the rendered dataset, once SUCCEEDED.

string
episodeCount

Episodes in it, once SUCCEEDED.

string
frameCount

Frames in it, once SUCCEEDED.

string
renderer

“b3:”: the renderer revision this rendering is for. A new renderer starts over at NOT_STARTED.

string
Example 
{
  "state": "STATE_UNSPECIFIED"
}

default

Section titled “default ”

Default error response

Media type application/json
One of:
API error

A refusal from the API itself.

object
code
required

The gRPC code name in upper case, e.g. NOT_FOUND.

string
message
required
string
retryable
required

Whether the same call may succeed if retried.

boolean
details
required

Empty, except when a dataset copy or move is refused: then one google.rpc.ErrorInfo with the refusal’s reason code, its domain and, in metadata, the datasets it names.

Array<object>
object
Example generated
{
  "code": "example",
  "message": "example",
  "retryable": true,
  "details": [
    {}
  ]
}