TaskDrafts_CreateTaskDraft
const url = 'https://dev-api.qualiastudios.dev/v1/accounts/example/tasks/example/drafts';const options = { method: 'POST', headers: {'X-API-Key': '<X-API-Key>', 'Content-Type': 'application/json'}, body: '{"parent":"example","validateOnly":true,"model":"example","maxCost":"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://dev-api.qualiastudios.dev/v1/accounts/example/tasks/example/drafts \ --header 'Content-Type: application/json' \ --header 'X-API-Key: <X-API-Key>' \ --data '{ "parent": "example", "validateOnly": true, "model": "example", "maxCost": "example" }'Prices all of a Task’s selected references, or starts a stored proposal. A create here does not mutate the Task or publish a revision. (— api-linter: core::0133::response-message-name=disabled aip.dev/not-precedent: the estimate-only and create modes share one endpoint; the response includes the estimate and optional proposal. —) (— api-linter: core::0133::http-body=disabled aip.dev/not-precedent: validate_only and pricing options are not TaskDraft resource fields; the request body contains these options. —)
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The account id.
The task id.
Request Body required
Section titled “Request Body required ”Price or start a TaskDraft from the Task’s person-picked references. (— api-linter: core::0133::request-resource-field=disabled aip.dev/not-precedent: the Task owns the references; qds reads them itself rather than accepting a client-authored TaskDraft resource. —) (— api-linter: core::0133::request-unknown-fields=disabled aip.dev/not-precedent: model and max_cost select pipeline execution and limit spending, not the TaskDraft’s persisted content. —) (— api-linter: core::0133::request-id-field=disabled aip.dev/not-precedent: this is a billed operation with a generated id; no caller-chosen TaskDraft id is accepted by this temporary qds seam. —)
object
The Task with the already-picked references.
If true, price all references without reserving credits or starting a run.
A registry model, or the default when omitted.
Optional maximum credits the person permits this run to reserve.
Example generated
{ "parent": "example", "validateOnly": true, "model": "example", "maxCost": "example"}Responses
Section titled “ Responses ”OK
Estimate, with the stored proposal when validate_only was false.
object
The pending or failed run; absent when validate_only is true.
object
Accounts/{account}/tasks/{task}/drafts/{draft}.
Current state of the run.
The exact references picked when the run started, not a live task read. (— api-linter: core::0122::embedded-resource=disabled aip.dev/not-precedent: this is a frozen reference snapshot, not an embedded independently editable resource. —)
An episode proposed to show the task: done (SUCCESS), or going wrong in a named way (a FAILURE or RECOVERY mode). A reference points at the episode and copies no media, so it lives while its task and its dataset do: deleting the task deletes it, and deleting the dataset removes it (the task and everything written from the reference stay). Nothing is confirmed for a person: a model’s proposal needs a person’s confirmation.
A task holds 1 to 3 SUCCESS references and any number of modes, each 1 to 2 references. Picking one needs read access to the episode’s dataset.
object
Accounts/{account}/tasks/{task}/references/{reference}
What it shows.
FAILURE and RECOVERY: the mode’s short name, e.g. “drops the box”, which groups the references that show it. 1 to 80 characters; a mode has one role. Empty for SUCCESS.
The episode: accounts/{account}/datasets/{dataset}/episodes/{episode}, in the task’s account; immutable. Named by the upload it was recorded in (Episode.upload), or by the merged dataset that holds that upload; it is kept and returned as its upload names it, and lives as long as that upload does.
The part of the episode it shows, in seconds from its start. Both unset means the whole episode; when set, 0 <= start_seconds < end_seconds.
See start_seconds.
Who picked 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 the model id (e.g. “gemini-robotics-er”), 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 picked.
Who proposed it. A person’s own pick is confirmed immediately. (— api-linter: core::0140::prepositions=disabled aip.dev/not-precedent: provenance distinguishes proposed_by from confirmed_by. —)
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 the model id (e.g. “gemini-robotics-er”), 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.
The first person to confirm it; unset while unconfirmed. (— api-linter: core::0140::prepositions=disabled aip.dev/not-precedent: provenance distinguishes confirmed_by from proposed_by. —)
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 the model id (e.g. “gemini-robotics-er”), 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.
The model’s five TaskSpec text fields and proposed procedure.
object
What the robot should do, in ordinary language. Required to publish.
The scene the task runs in: the workspace, the objects that matter, how things start and what varies between episodes.
The steps of the task in order, one per line, e.g. “pick a box from the tray”.
How success shows: what has to be true, or seen happening, for an episode to succeed. Required to publish.
How it fails: the ways the task goes wrong, and what looks like a failure but is fine.
The task as a state machine of steps and transitions, beside the prose. Optional; when it has steps, publishing checks that it is well formed.
object
The steps. Step ids are the stable names judgments, subtask labels and progress report against. At most 64.
A state of the task: its start, an action, a recovery, or an outcome it ends in.
object
Stable within the procedure, e.g. “place_box”: given by the editor when the step is made and not changed after. 1 to 64 lowercase letters, digits or ’_’, starting with a letter. Unique within the procedure.
What the step is.
The step in one line, as it observably holds: what an action or
recovery gets done (e.g. “place the box upright on the shelf”), what an
outcome looks like. At most 200 characters. Needed to publish, except on
the start and on a step that stands for a task (task), which is named
by the task.
An action that is a whole other task of the same account,
accounts/{account}/tasks/{task}. In a draft it means that task’s newest
published revision; publishing pins it, so a revision’s steps name
accounts/{account}/tasks/{task}/revisions/{revision}. A task never
contains itself, directly or through others. Such a step takes its name
from the task and leaves description empty.
The fewest times an action (or recovery) happens in a successful
attempt: 0 or more; 0 makes it optional, e.g. a step only some attempts
need. With both counts unset the step is not counted: checks report how
often it happened and never flag it. Checks enforce a count only when
count_set names the person who set it.
The most times an action (or recovery) happens in a successful attempt,
e.g. 4 box placements: 1 or more, and at least min_count. Unset is no
limit. Exactly N is both N; up to N is max_count N alone.
What observably sets a recovery off (“When”), e.g. “the box slips in the gripper”. Only a recovery has triggers, and it needs one to publish. At most 16, each 1 to 500 characters.
Conditions that observably hold at this step. At most 16; each needs text to publish and may also name a numeric condition. Not on START.
An observable condition at a procedure step, optionally expressed as a number.
object
What must hold, in 1 to 500 characters. Needed to publish.
A numeric form of the condition, when it can be measured. Only a person
writes one: it publishes only with numeric_set.
object
The metric name: 1 to 64 lowercase letters, digits, ’_’ or ’.’, starting with a letter.
The comparison: lt, le, gt, ge, eq or between.
The comparison value, or the lower value for between.
The upper value, greater than value. Set if and only if op is between.
The person who set numeric to its current value. Written only by the
server, from UpdateTaskRequest.person_set. It follows the numeric form
within its step and is cleared when that form changes without it.
object
The person, always kind PERSON, with user and display_name as at
the time.
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 the model id (e.g. “gemini-robotics-er”), 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 they set it.
Lowercase hex sha256 of the value. For counts:
“count:<min_count>:<max_count>”, each empty when unset. For a numeric
condition: “numeric:
Metric limits for this step. At most 8. Not on START.
Inclusive limits for a measured metric at a procedure step.
object
The metric name: 1 to 64 lowercase letters, digits, ’_’ or ’.’, starting with a letter.
The lower limit. At least one of min and max is needed to publish.
The upper limit, at least min when both are set.
The person who set min_count and max_count to their current values.
Written only by the server, from UpdateTaskRequest.person_set; cleared
when either count, the kind or task changes without it. Unset means the
counts are not enforced, whatever they are.
object
The person, always kind PERSON, with user and display_name as at
the time.
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 the model id (e.g. “gemini-robotics-er”), 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 they set it.
Lowercase hex sha256 of the value. For counts:
“count:<min_count>:<max_count>”, each empty when unset. For a numeric
condition: “numeric:
How steps follow each other, each from one step to another; nothing is implied. A failure outcome that can happen at several steps has a transition from each. At most 256.
A move from one step to another.
object
The step it leaves, by id.
The step it enters, by id.
The signed-in person whose edit wrote these steps and transitions.
Written only by the server, on any UpdateTask from such a person that
changes them. An API key’s change or a new proposal from preparation
clears it. Unset on a draft, the step-order check reads uncertain instead
of failing a take. It is left out of content_hash.
object
The person, always kind PERSON, with user and display_name as at
the time.
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 the model id (e.g. “gemini-robotics-er”), 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 they set it.
Lowercase hex sha256 of the value. For counts:
“count:<min_count>:<max_count>”, each empty when unset. For a numeric
condition: “numeric:
Valid, valid_after_retry or dropped; only valid graphs can be applied.
The VLM model used to create this proposal.
Credits estimated for the full selection and synthesis.
Person-specified spending cap, or zero when none was specified.
Failure reason, if the run did not produce a usable proposal.
When the proposal was requested.
When its status was last refreshed.
Credits to reserve for all selected references and synthesis.
Minimum credits reported by this reservation estimate.
Example
{ "taskDraft": { "state": "STATE_UNSPECIFIED", "references": [ { "role": "ROLE_UNSPECIFIED", "creator": { "kind": "KIND_UNSPECIFIED", "attribution": { "authentication": "AUTHENTICATION_UNSPECIFIED", "credentialOwner": "CREDENTIAL_OWNER_UNSPECIFIED" } }, "proposedBy": { "kind": "KIND_UNSPECIFIED", "attribution": { "authentication": "AUTHENTICATION_UNSPECIFIED", "credentialOwner": "CREDENTIAL_OWNER_UNSPECIFIED" } }, "confirmedBy": { "kind": "KIND_UNSPECIFIED", "attribution": { "authentication": "AUTHENTICATION_UNSPECIFIED", "credentialOwner": "CREDENTIAL_OWNER_UNSPECIFIED" } } } ], "proposal": { "procedure": { "steps": [ { "kind": "KIND_UNSPECIFIED", "stateChecks": [ { "numericSet": { "actor": { "kind": "KIND_UNSPECIFIED", "attribution": { "authentication": "AUTHENTICATION_UNSPECIFIED", "credentialOwner": "CREDENTIAL_OWNER_UNSPECIFIED" } } } } ], "countSet": { "actor": { "kind": "KIND_UNSPECIFIED", "attribution": { "authentication": "AUTHENTICATION_UNSPECIFIED", "credentialOwner": "CREDENTIAL_OWNER_UNSPECIFIED" } } } } ], "procedureSet": { "actor": { "kind": "KIND_UNSPECIFIED", "attribution": { "authentication": "AUTHENTICATION_UNSPECIFIED", "credentialOwner": "CREDENTIAL_OWNER_UNSPECIFIED" } } } } } }}default
Section titled “default ”Default error response
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
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
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.
A list of messages that carry the error details. There is a common set of message types for APIs to use.
Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.
object
The type of the serialized message.
Example generated
{ "code": 1, "message": "example", "details": [ { "@type": "example" } ]}