Versions_CreateVersion

POST

/v1/accounts/{account}/datasets/{dataset}/versions

curl --request POST \
  --url https://dev-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 (QUA-3615); 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, QUA-3511); its tags keep resolving. Emits VERSION_CREATED.

Authorizations

• ApiKey

Parameters

Path Parameters

account

required

string

The account id.

dataset

required

string

The dataset id.

Query Parameters

versionId

string

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.

requestId

string

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

Media type application/json

A version tag: a human name on what a dataset yielded at one moment (QUA-2236). 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 (QUA-2237): stable (the newest tag) and head (what the dataset yields now; a Version with no tag). Any other id that is not a tag is matched as a digest prefix (7+ hex characters) over the dataset’s tagged digests.

Served by qds-api.

object

name

Accounts/{account}/datasets/{dataset}/versions/{version}

string

tag

The tag name (“1.0”); empty for head.

string

digest

Opaque episode-set identity, “b3:”, for the (episode id, episode revision) pairs the ref yields. Head and tags use the same account-scoped identity. Upgrades preserve current heads and retained version digests. Clients compare returned identities rather than computing them. On CreateVersion, optionally the head digest seen in the tag dialog: when head has moved since, the call fails with ABORTED instead of tagging something nobody saw.

string

episodeCount

Episodes it pins.

string

durationSeconds

Recorded time it pins, seconds.

number format: double

rejectedCount

Episodes the dataset itself had rejected (inherited by whoever reads it).

string

manifest

Per upload: how finished it was.

Array<object>

How finished one upload was when the version was cut (QUA-2238).

object

dataset

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 (QUA-3511); a merged dataset’s own versions name its uploads.

string

reviewedCount

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).

string

totalCount

Episodes in the upload.

string

memberCount

Episodes the version took from it.

string

lock

Per mixture source: what it resolved to. Empty for an upload.

Array<object>

What one mixture source resolved to when the version was cut: the lockfile row.

object

source

Accounts/{account}/datasets/{dataset}/sources/{source}

string

dataset

Accounts/{account}/datasets/{dataset}: the dataset it resolved to.

string

follow

The follow it had.

object

channel

Move with a channel.

string format: enum

Allowed values: CHANNEL_UNSPECIFIED STABLE HEAD

pin

Stay on this version tag of the source dataset, e.g. “1.0”.

string

ref

The tag it stood at, or “head”.

string

digest

The digest it stood at.

string

episodeCount

Episodes it brought in.

string

note

What the version is, in a person’s words. Editable after the cut (QUA-1837).

string

reference

The reference a training run cites: “<Dataset.slug>:”, e.g. “restock-shelf-mix:1.0”. Unique per account.

string

creator

Who cut it.

object

kind

What kind of actor it is.

string format: enum

Allowed values: KIND_UNSPECIFIED PERSON VALIDATION RULE MODEL OPERATOR SYSTEM

user

The person’s user id when kind is PERSON; empty otherwise.

string

displayName

The person’s display name at the time, for rendering without a lookup.

string

agent

The rule code, or the model id (e.g. “gemini-robotics-er”), when not a person.

string

run

The run a model or rule finding came from, when it has one.

string

apiKey

The API key’s id when a person acted through one; empty for a session. Never the key itself.

string

attribution

Signed identity evidence recorded with the change, kept apart from the principal above. Unset on older records and wherever none was signed.

object

authentication

How the principal authenticated.

string format: enum

Allowed values: AUTHENTICATION_UNSPECIFIED SESSION API_KEY SERVICE

initiator

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.

string

initiatorDisplayName

The initiator’s display name at the time, never their email.

string

credentialCreator

The user id of the key’s creator at the time. Not who used the key.

string

credentialOwner

Who owned the key at the time.

string format: enum

Allowed values: CREDENTIAL_OWNER_UNSPECIFIED PERSON SPACE

credentialOwnerSpace

The owning space’s id (a workspace or the organization) when credential_owner is SPACE.

string

createTime

When it was cut.

string format: date-time

updateTime

When the note last changed.

string format: date-time

etag

Sent back on UpdateVersion.

string

datasetVersionId

The immutable dataset version the tag pins, a UUID: the id training, materialization and health reads take (QUA-3048). Tags of one digest may share it. Empty for head, which pins nothing.

string

copySource

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

datasetDisplayName

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.

string

workspaceDisplayName

The source’s workspace’s name; empty when no record names it.

string

organizationDisplayName

The source’s organization’s name; set only for another organization.

string

version

The source’s version tag; empty for the version it stood at then.

string

copyTime

When the copy was made.

string format: date-time

preview

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.

string

include

Which takes the preview took, by how they stood. Empty when preview is.

Array<string>

Allowed values: CLASS_UNSPECIFIED KEPT_BY_PERSON KEPT FLAGGED REJECTED REJECTED_BY_PERSON

includedFlaggedCount

Episodes it pins that stood FLAGGED when the preview was made.

string

includedRejectedCount

Episodes it pins that stood REJECTED when the preview was made.

string

editedCount

Takes published with the edit drawn on them. 0 for a tag of head, which has every take as recorded.

string

trimmedCount

Edited takes published as one new episode (a trim, new subtasks or both).

string

splitCount

Edited takes published as two or more new episodes.

string

pieceCount

New episodes the edited takes became, across every edited take.

string

draftsNotIncluded

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.

string

Responses

200

OK

Media type application/json

A version tag: a human name on what a dataset yielded at one moment (QUA-2236). 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 (QUA-2237): stable (the newest tag) and head (what the dataset yields now; a Version with no tag). Any other id that is not a tag is matched as a digest prefix (7+ hex characters) over the dataset’s tagged digests.

Served by qds-api.

object

name

Accounts/{account}/datasets/{dataset}/versions/{version}

string

tag

The tag name (“1.0”); empty for head.

string

digest

Opaque episode-set identity, “b3:”, for the (episode id, episode revision) pairs the ref yields. Head and tags use the same account-scoped identity. Upgrades preserve current heads and retained version digests. Clients compare returned identities rather than computing them. On CreateVersion, optionally the head digest seen in the tag dialog: when head has moved since, the call fails with ABORTED instead of tagging something nobody saw.

string

episodeCount

Episodes it pins.

string

durationSeconds

Recorded time it pins, seconds.

number format: double

rejectedCount

Episodes the dataset itself had rejected (inherited by whoever reads it).

string

manifest

Per upload: how finished it was.

Array<object>

How finished one upload was when the version was cut (QUA-2238).

object

dataset

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 (QUA-3511); a merged dataset’s own versions name its uploads.

string

reviewedCount

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).

string

totalCount

Episodes in the upload.

string

memberCount

Episodes the version took from it.

string

lock

Per mixture source: what it resolved to. Empty for an upload.

Array<object>

What one mixture source resolved to when the version was cut: the lockfile row.

object

source

Accounts/{account}/datasets/{dataset}/sources/{source}

string

dataset

Accounts/{account}/datasets/{dataset}: the dataset it resolved to.

string

follow

The follow it had.

object

channel

Move with a channel.

string format: enum

Allowed values: CHANNEL_UNSPECIFIED STABLE HEAD

pin

Stay on this version tag of the source dataset, e.g. “1.0”.

string

ref

The tag it stood at, or “head”.

string

digest

The digest it stood at.

string

episodeCount

Episodes it brought in.

string

note

What the version is, in a person’s words. Editable after the cut (QUA-1837).

string

reference

The reference a training run cites: “<Dataset.slug>:”, e.g. “restock-shelf-mix:1.0”. Unique per account.

string

creator

Who cut it.

object

kind

What kind of actor it is.

string format: enum

Allowed values: KIND_UNSPECIFIED PERSON VALIDATION RULE MODEL OPERATOR SYSTEM

user

The person’s user id when kind is PERSON; empty otherwise.

string

displayName

The person’s display name at the time, for rendering without a lookup.

string

agent

The rule code, or the model id (e.g. “gemini-robotics-er”), when not a person.

string

run

The run a model or rule finding came from, when it has one.

string

apiKey

The API key’s id when a person acted through one; empty for a session. Never the key itself.

string

attribution

Signed identity evidence recorded with the change, kept apart from the principal above. Unset on older records and wherever none was signed.

object

authentication

How the principal authenticated.

string format: enum

Allowed values: AUTHENTICATION_UNSPECIFIED SESSION API_KEY SERVICE

initiator

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.

string

initiatorDisplayName

The initiator’s display name at the time, never their email.

string

credentialCreator

The user id of the key’s creator at the time. Not who used the key.

string

credentialOwner

Who owned the key at the time.

string format: enum

Allowed values: CREDENTIAL_OWNER_UNSPECIFIED PERSON SPACE

credentialOwnerSpace

The owning space’s id (a workspace or the organization) when credential_owner is SPACE.

string

createTime

When it was cut.

string format: date-time

updateTime

When the note last changed.

string format: date-time

etag

Sent back on UpdateVersion.

string

datasetVersionId

The immutable dataset version the tag pins, a UUID: the id training, materialization and health reads take (QUA-3048). Tags of one digest may share it. Empty for head, which pins nothing.

string

copySource

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

datasetDisplayName

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.

string

workspaceDisplayName

The source’s workspace’s name; empty when no record names it.

string

organizationDisplayName

The source’s organization’s name; set only for another organization.

string

version

The source’s version tag; empty for the version it stood at then.

string

copyTime

When the copy was made.

string format: date-time

preview

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.

string

include

Which takes the preview took, by how they stood. Empty when preview is.

Array<string>

Allowed values: CLASS_UNSPECIFIED KEPT_BY_PERSON KEPT FLAGGED REJECTED REJECTED_BY_PERSON

includedFlaggedCount

Episodes it pins that stood FLAGGED when the preview was made.

string

includedRejectedCount

Episodes it pins that stood REJECTED when the preview was made.

string

editedCount

Takes published with the edit drawn on them. 0 for a tag of head, which has every take as recorded.

string

trimmedCount

Edited takes published as one new episode (a trim, new subtasks or both).

string

splitCount

Edited takes published as two or more new episodes.

string

pieceCount

New episodes the edited takes became, across every edited take.

string

draftsNotIncluded

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.

string

Example

{
  "lock": [
    {
      "follow": {
        "channel": "CHANNEL_UNSPECIFIED"
      }
    }
  ],
  "creator": {
    "kind": "KIND_UNSPECIFIED",
    "attribution": {
      "authentication": "AUTHENTICATION_UNSPECIFIED",
      "credentialOwner": "CREDENTIAL_OWNER_UNSPECIFIED"
    }
  },
  "include": [
    "CLASS_UNSPECIFIED"
  ]
}

default

Default error response

Media type application/json

The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

object

code

The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

integer format: int32

message

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

string

details

A list of messages that carry the error details. There is a common set of message types for APIs to use.

Array<object>

Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.

object

@type

The type of the serialized message.

string

key

additional properties

any

Example ^generated

{
  "code": 1,
  "message": "example",
  "details": [
    {
      "@type": "example"
    }
  ]
}