Versions_CreateVersion
const url = 'https://junction-api.qualiastudios.dev/v1/accounts/example/datasets/example/versions';const options = { method: 'POST', headers: {'X-API-Key': '<X-API-Key>', 'Content-Type': 'application/json'}, body: '{"name":"example","digest":"example","note":"example","etag":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://junction-api.qualiastudios.dev/v1/accounts/example/datasets/example/versions \ --header 'Content-Type: application/json' \ --header 'X-API-Key: <X-API-Key>' \ --data '{ "name": "example", "digest": "example", "note": "example", "etag": "example" }'Tags what the dataset yields now. ALREADY_EXISTS when the name is taken;
FAILED_PRECONDITION when the dataset holds no episode at all, or while a
trim of an episode it holds is still being applied, naming them; ABORTED when version.digest is set and head has moved. A
head with every episode rejected is tagged: its version has
episode_count 0, records why in its note, and training and export
refuse it (FAILED_PRECONDITION).
Reuses the dataset version whose episode-set digest equals head’s, else
pins one from head’s exact member revisions (version_kind ‘tag’). A merged
dataset is tagged only when every upload it holds freezes the same training
contract (see MergeDatasets): else FAILED_PRECONDITION naming two uploads
and what differs. An upload merged into one is tagged no more
(FAILED_PRECONDITION naming the merged dataset); its tags keep
resolving. Emits VERSION_CREATED.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The account id.
The dataset id.
Query Parameters
Section titled “Query Parameters ”The tag name: 1-64 characters of [0-9A-Za-z._-], starting with a letter
or digit; not stable or head; not all hex. Unique per dataset.
Idempotency key (AIP-155): a retry with the same id within 24 hours returns the first call’s result instead of failing ALREADY_EXISTS.
Request Body required
Section titled “Request Body required ”A version tag: a human name on what a dataset yielded at one moment. Uploads and mixtures both have them. A tag never moves; many tags may share a digest.
The {version} id is the tag name. Two reserved ids resolve instead of
naming a tag: stable (the newest tag) and head (what the
dataset yields now; a Version with no tag).
A DatasetVersion id (dataset_version_id, what an upload prints) names
the version that has it; a tag cut with that UUID as its name, before such
names were refused, answers first, and FAILED_PRECONDITION when the two
are different versions. Any other id that is not a tag is matched as a
prefix (7+ hex characters) of the dataset’s version digests and of their
DatasetVersion ids without dashes. Those include an upload’s
v0, which has no tag row.
Served by qds-api.
object
Accounts/{account}/datasets/{dataset}/versions/{version}
The tag name (“1.0”); empty for head.
Opaque episode-set identity, “b3:
Episodes it pins.
Recorded time it pins, seconds.
Episodes the dataset itself had rejected (inherited by whoever reads it).
Per upload: how finished it was.
How finished one upload was when the version was cut.
object
Accounts/{account}/datasets/{dataset}: the upload. A mixture’s version names an upload a merge took by its merged dataset, one entry for all the uploads it holds, their counts summed; a merged dataset’s own versions name its uploads.
Episodes a person or validation had ruled on. On v0, 0: nothing was
ruled yet, except on a copy, whose rulings came with it and were not
counted (see Version.copy_source).
Episodes in the upload.
Episodes the version took from it.
Per mixture source: what it resolved to. Empty for an upload.
What one mixture source resolved to when the version was cut: the lockfile row.
object
Accounts/{account}/datasets/{dataset}/sources/{source}
Accounts/{account}/datasets/{dataset}: the dataset it resolved to.
The follow it had.
object
Move with a channel.
Stay on this version tag of the source dataset, e.g. “1.0”.
The tag it stood at, or “head”.
The digest it stood at.
Episodes it brought in.
What the version is, in a person’s words. Editable after the cut.
The reference a training run cites: “<Dataset.slug>:
Who cut it.
object
What kind of actor it is.
The person’s user id when kind is PERSON; empty otherwise.
The person’s display name at the time, for rendering without a lookup.
The rule code, or for a MODEL the Qualia model tier (e.g. “qualia-vlm”; “qualia” for any other model), when not a person.
The run a model or rule finding came from, when it has one.
The API key’s id when a person acted through one; empty for a session. Never the key itself.
Signed identity evidence recorded with the change, kept apart from the principal above. Unset on older records and wherever none was signed.
object
How the principal authenticated.
The user id of a person verified as starting the work: the person of a session, or the person a trusted service’s signed job record names. Empty when nobody was verified.
The initiator’s display name at the time, never their email.
The user id of the key’s creator at the time. Not who used the key.
Who owned the key at the time.
The owning space’s id (a workspace or the organization) when
credential_owner is SPACE.
When it was cut.
When the note last changed.
Sent back on UpdateVersion.
The immutable dataset version the tag pins, a UUID: the id training, materialization and health reads take. Tags of one digest may share it. Empty for head, which pins nothing.
Set only on v0 of a copy, which holds what the copy started with rather
than what an upload arrived with. ListVersionsResponse.copy_source says the
same of any dataset, v0 or not.
object
The source dataset’s name. Empty for a source in another organization, and for an upload forked for a copied mixture, which has no record of its own.
The source’s workspace’s name; empty when no record names it.
The source’s organization’s name; set only for another organization.
The source’s version tag; empty for the version it stood at then.
When the copy was made.
Accounts/{account}/datasets/{dataset}/versionPreviews/{version_preview}: the preview the tag was published from (PublishVersionPreview). Empty for a tag of head (CreateVersion), and for head itself.
Which takes the preview took, by how they stood. Empty when preview is.
Episodes it pins that stood FLAGGED when the preview was made.
Episodes it pins that stood REJECTED when the preview was made.
Takes published with the edit drawn on them. 0 for a tag of head, which has every take as recorded.
Edited takes published as one new episode (a trim, new subtasks or both).
Edited takes published as two or more new episodes.
New episodes the edited takes became, across every edited take.
Takes with an edit drawn and not published when a tag of head was made: the tag has them as recorded. 0 for a tag published from a preview.
Responses
Section titled “ Responses ”OK
A version tag: a human name on what a dataset yielded at one moment. Uploads and mixtures both have them. A tag never moves; many tags may share a digest.
The {version} id is the tag name. Two reserved ids resolve instead of
naming a tag: stable (the newest tag) and head (what the
dataset yields now; a Version with no tag).
A DatasetVersion id (dataset_version_id, what an upload prints) names
the version that has it; a tag cut with that UUID as its name, before such
names were refused, answers first, and FAILED_PRECONDITION when the two
are different versions. Any other id that is not a tag is matched as a
prefix (7+ hex characters) of the dataset’s version digests and of their
DatasetVersion ids without dashes. Those include an upload’s
v0, which has no tag row.
Served by qds-api.
object
Accounts/{account}/datasets/{dataset}/versions/{version}
The tag name (“1.0”); empty for head.
Opaque episode-set identity, “b3:
Episodes it pins.
Recorded time it pins, seconds.
Episodes the dataset itself had rejected (inherited by whoever reads it).
Per upload: how finished it was.
How finished one upload was when the version was cut.
object
Accounts/{account}/datasets/{dataset}: the upload. A mixture’s version names an upload a merge took by its merged dataset, one entry for all the uploads it holds, their counts summed; a merged dataset’s own versions name its uploads.
Episodes a person or validation had ruled on. On v0, 0: nothing was
ruled yet, except on a copy, whose rulings came with it and were not
counted (see Version.copy_source).
Episodes in the upload.
Episodes the version took from it.
Per mixture source: what it resolved to. Empty for an upload.
What one mixture source resolved to when the version was cut: the lockfile row.
object
Accounts/{account}/datasets/{dataset}/sources/{source}
Accounts/{account}/datasets/{dataset}: the dataset it resolved to.
The follow it had.
object
Move with a channel.
Stay on this version tag of the source dataset, e.g. “1.0”.
The tag it stood at, or “head”.
The digest it stood at.
Episodes it brought in.
What the version is, in a person’s words. Editable after the cut.
The reference a training run cites: “<Dataset.slug>:
Who cut it.
object
What kind of actor it is.
The person’s user id when kind is PERSON; empty otherwise.
The person’s display name at the time, for rendering without a lookup.
The rule code, or for a MODEL the Qualia model tier (e.g. “qualia-vlm”; “qualia” for any other model), when not a person.
The run a model or rule finding came from, when it has one.
The API key’s id when a person acted through one; empty for a session. Never the key itself.
Signed identity evidence recorded with the change, kept apart from the principal above. Unset on older records and wherever none was signed.
object
How the principal authenticated.
The user id of a person verified as starting the work: the person of a session, or the person a trusted service’s signed job record names. Empty when nobody was verified.
The initiator’s display name at the time, never their email.
The user id of the key’s creator at the time. Not who used the key.
Who owned the key at the time.
The owning space’s id (a workspace or the organization) when
credential_owner is SPACE.
When it was cut.
When the note last changed.
Sent back on UpdateVersion.
The immutable dataset version the tag pins, a UUID: the id training, materialization and health reads take. Tags of one digest may share it. Empty for head, which pins nothing.
Set only on v0 of a copy, which holds what the copy started with rather
than what an upload arrived with. ListVersionsResponse.copy_source says the
same of any dataset, v0 or not.
object
The source dataset’s name. Empty for a source in another organization, and for an upload forked for a copied mixture, which has no record of its own.
The source’s workspace’s name; empty when no record names it.
The source’s organization’s name; set only for another organization.
The source’s version tag; empty for the version it stood at then.
When the copy was made.
Accounts/{account}/datasets/{dataset}/versionPreviews/{version_preview}: the preview the tag was published from (PublishVersionPreview). Empty for a tag of head (CreateVersion), and for head itself.
Which takes the preview took, by how they stood. Empty when preview is.
Episodes it pins that stood FLAGGED when the preview was made.
Episodes it pins that stood REJECTED when the preview was made.
Takes published with the edit drawn on them. 0 for a tag of head, which has every take as recorded.
Edited takes published as one new episode (a trim, new subtasks or both).
Edited takes published as two or more new episodes.
New episodes the edited takes became, across every edited take.
Takes with an edit drawn and not published when a tag of head was made: the tag has them as recorded. 0 for a tag published from a preview.
Example
{ "lock": [ { "follow": { "channel": "CHANNEL_UNSPECIFIED" } } ], "creator": { "kind": "KIND_UNSPECIFIED", "attribution": { "authentication": "AUTHENTICATION_UNSPECIFIED", "credentialOwner": "CREDENTIAL_OWNER_UNSPECIFIED" } }, "include": [ "CLASS_UNSPECIFIED" ]}default
Section titled “default ”Default error response
A refusal from the API itself.
object
The gRPC code name in upper case, e.g. NOT_FOUND.
Whether the same call may succeed if retried.
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.
object
A refusal from the gateway before the call reaches the API, for example 401 bad or missing API key, 403 key lacks the scope or environment closed, 413 body too large.
object
What went wrong.
Example generated
{ "code": "example", "message": "example", "retryable": true, "details": [ {} ]}