{ "openapi": "3.0.3", "info": { "title": "Qualia API", "version": "qualia.v1", "description": "The Qualia API, defined in protobuf as `qualia.v1`. Every resource lives under `/v1/accounts/{account}`, where `{account}` is your account id, a lowercase UUID.\n\n**Base URL:** `https://junction-api.qualiastudios.dev`\n\nAuthenticate with an API key in the `X-API-Key` header. Create one in **Settings** in the [Qualia dashboard](https://junction.qualiastudios.dev). `GET` calls need the key's `data:read` scope; every other call needs `data:write`.\n\nEvery call is also served over Connect at `POST /qualia.v1./`.\n\nA call the API refuses returns the gRPC code name in upper case, for example `{\"code\": \"NOT_FOUND\", \"message\": \"…\", \"retryable\": false, \"details\": []}`. Another account's resources answer `NOT_FOUND`. `retryable` is true for `ABORTED`, `UNAVAILABLE`, `RESOURCE_EXHAUSTED`, `DEADLINE_EXCEEDED` and `CANCELED`.\n\nA request the gateway stops before it reaches the API has a different body: `{\"detail\": \"…\"}`. For example: a missing or invalid API key (`401`), a key without the scope or the resources the call needs (`403` or `404`), an environment closed to you (`403`), or a body over the size limit (`413`). Read `code` if the body has one, otherwise `detail`.\n\n**OpenAPI document:** [https://junction-docs.qualiastudios.dev/api/qualia-v1/openapi.json](https://junction-docs.qualiastudios.dev/api/qualia-v1/openapi.json)" }, "servers": [ { "url": "https://junction-api.qualiastudios.dev" } ], "paths": { "/v1/accounts/{account}/checkPolicies/{checkPolicy}": { "get": { "tags": [ "Checks" ], "description": "Reads the effective policy and its source for each scheduler half.", "operationId": "Checks_GetAutomaticCheckPolicy_Account", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "checkPolicy", "in": "path", "description": "The checkPolicy id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.AutomaticCheckPolicy" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } }, "patch": { "tags": [ "Checks" ], "description": "Updates only the selected halves; an inherit value removes that override.", "operationId": "Checks_UpdateAutomaticCheckPolicy_Account", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "checkPolicy", "in": "path", "description": "The checkPolicy id.", "required": true, "schema": { "type": "string" } }, { "name": "updateMask", "in": "query", "description": "The halves to change: heuristic, graph, or both. Omitted halves stay put.\n A selected field set to SETTING_UNSPECIFIED clears its override.", "schema": { "type": "string", "format": "field-mask" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.AutomaticCheckPolicy" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.AutomaticCheckPolicy" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/checks": { "get": { "tags": [ "Checks" ], "description": "Lists the checks.", "operationId": "Checks_ListChecks", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "At most this many; 0 means 100, the maximum is 1000.", "schema": { "type": "integer", "format": "int32" } }, { "name": "pageToken", "in": "query", "description": "From a previous response's next_page_token.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.ListChecksResponse" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/checks/{check}": { "get": { "tags": [ "Checks" ], "description": "Gets one check.", "operationId": "Checks_GetCheck", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "check", "in": "path", "description": "The check id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.Check" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/checks/{check}/referenceRanges": { "get": { "tags": [ "Checks" ], "description": "Lists a check's reference ranges. The check may be `-` to list every\n check's.", "operationId": "Checks_ListReferenceRanges", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "check", "in": "path", "description": "The check id.", "required": true, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "At most this many; 0 means 100, the maximum is 1000.", "schema": { "type": "integer", "format": "int32" } }, { "name": "pageToken", "in": "query", "description": "From a previous response's next_page_token.", "schema": { "type": "string" } }, { "name": "filter", "in": "query", "description": "AIP-160 filter. Fields: interface_hash, robot, metric.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.ListReferenceRangesResponse" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/checks/{check}/referenceRanges/{referenceRange}": { "get": { "tags": [ "Checks" ], "description": "Gets one reference range.", "operationId": "Checks_GetReferenceRange", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "check", "in": "path", "description": "The check id.", "required": true, "schema": { "type": "string" } }, { "name": "referenceRange", "in": "path", "description": "The referenceRange id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.ReferenceRange" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/checks/{check}/referenceRanges/{referenceRange}:confirm": { "post": { "tags": [ "Checks" ], "description": "Replaces a reference range's confirmed bounds, or clears the confirmation.", "operationId": "Checks_ConfirmReferenceRange", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "check", "in": "path", "description": "The check id.", "required": true, "schema": { "type": "string" } }, { "name": "referenceRange", "in": "path", "description": "The referenceRange id.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.ConfirmReferenceRangeRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.ReferenceRange" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/checks/{check}/results": { "get": { "tags": [ "Checks" ], "description": "Lists a check's results. The check may be `-` to list every check's.", "operationId": "Checks_ListCheckResults", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "check", "in": "path", "description": "The check id.", "required": true, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "At most this many; 0 means 100, the maximum is 1000.", "schema": { "type": "integer", "format": "int32" } }, { "name": "pageToken", "in": "query", "description": "From a previous response's next_page_token.", "schema": { "type": "string" } }, { "name": "filter", "in": "query", "description": "AIP-160 filter. Fields: dataset, episode, state, reach.robot,\n reach.longest_seconds. `dataset` and `episode` take `=` only, ANDed at\n the top level, and choose the scope: `dataset = \"\"` lists that\n dataset's handheld and egocentric episodes that carry hand poses on its\n target robot (or the robots `reach.robot` names) at the dataset's\n current reach key (ReachStatus.current_key), reporting NOT_RUN for what\n is not yet computed under it, or, while nothing in the scope has a\n settled result under that key, at the key of the dataset's last finished\n run where that run stored results on the target robot (the last solve,\n under settings since changed; CheckResult.reach.key says which);\n `episode = \"\"` narrows that to one episode as its dataset sees\n it. Without either, every stored result of the account's workspace at\n each robot's current config, the newest key of each pair.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.ListCheckResultsResponse" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/checks/{check}/results/{result}": { "get": { "tags": [ "Checks" ], "description": "Gets one result: the newest stored for the pair at the robot's current\n model config (a dataset's own key is ListCheckResults'), NOT_RUN when\n there is none; reading queues nothing.", "operationId": "Checks_GetCheckResult", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "check", "in": "path", "description": "The check id.", "required": true, "schema": { "type": "string" } }, { "name": "result", "in": "path", "description": "The result id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.CheckResult" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/checks/{check}/results/{result}:readReachTrace": { "get": { "tags": [ "Checks" ], "description": "Read one result's bounded sampled solver joint trace. The key must still\n be current for the episode's target robot and settings (or be the key\n ReadReachTracesRequest.expected_key also admits); a stale key is\n FAILED_PRECONDITION, and a trace that could not be read just now is\n UNAVAILABLE. `max_frames` is at most 512 (0 means 512).", "operationId": "Checks_ReadReachTrace", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "check", "in": "path", "description": "The check id.", "required": true, "schema": { "type": "string" } }, { "name": "result", "in": "path", "description": "The result id.", "required": true, "schema": { "type": "string" } }, { "name": "expectedKey", "in": "query", "description": "The key from CheckResult.reach.trace. A stale trace is refused.", "schema": { "type": "string" } }, { "name": "maxFrames", "in": "query", "description": "At most 512 samples. 0 means the maximum.", "schema": { "type": "integer", "format": "int32" } }, { "name": "dataset", "in": "query", "description": "Current dataset scope whose settings and pose/calibration identity must\n still produce expected_key; this prevents reading an old shared result\n after placement changes in an upload or any member of a merged dataset.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.ReadReachTraceResponse" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/checks/{check}/runs": { "get": { "tags": [ "Checks" ], "description": "Lists a check's runs, newest first, in the caller's workspace. The check\n may be `-` to list every check's.", "operationId": "Checks_ListCheckRuns", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "check", "in": "path", "description": "The check id.", "required": true, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "At most this many; 0 means 100, the maximum is 1000.", "schema": { "type": "integer", "format": "int32" } }, { "name": "pageToken", "in": "query", "description": "From a previous response's next_page_token.", "schema": { "type": "string" } }, { "name": "filter", "in": "query", "description": "AIP-160 filter. Fields: dataset (a name, `=` and `!=`: a merged\n dataset's name lists its own runs and its uploads'), state, create_time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.ListCheckRunsResponse" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/checks/{check}/runs/{run}": { "get": { "tags": [ "Checks" ], "description": "Gets one run. NOT_FOUND outside the caller's workspace, and under\n another check than the one it ran.", "operationId": "Checks_GetCheckRun", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "check", "in": "path", "description": "The check id.", "required": true, "schema": { "type": "string" } }, { "name": "run", "in": "path", "description": "The run id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.CheckRun" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/checks/{check}/runs/{run}:cancel": { "post": { "tags": [ "Checks" ], "description": "Cancels a running VLM or heuristic run: its pipeline run is\n cancelled, which releases the credits it reserved, and the run ends\n FAILED with \"cancelled by\" who asked. A VLM run still QUEUED behind\n another ends so at once: it never starts and reserves nothing. Episodes\n it had not read keep their issues. The check may be `-`: a run's id\n names one run. Needs what RunCheck needs (a write on the dataset).\n FAILED_PRECONDITION for a run that has ended, one still starting its\n pipeline run (ask again in a few seconds) and any other check's run. A\n pipeline cancel that answered late or failed but took ends the run all\n the same. UNAVAILABLE when the pipeline could not be reached or did not\n answer in time and the run does not read cancelled after: it still runs;\n ask again. ABORTED when another cancel or end of a queued run keeps it\n busy: nothing changed; ask again. NOT_FOUND outside the caller's\n workspace.", "operationId": "Checks_CancelCheckRun", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "check", "in": "path", "description": "The check id.", "required": true, "schema": { "type": "string" } }, { "name": "run", "in": "path", "description": "The run id.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.CancelCheckRunRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.CheckRun" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/checks/{check}:run": { "post": { "tags": [ "Checks" ], "description": "Runs a check over a dataset again; `checks/-` runs the dataset's default\n set (an upload runs episode-rules, a mixture runs mixture; reach is never\n in it, name `checks/reach`). Answers as soon as the run is accepted,\n naming the checks started;\n they run in the background. Their findings land as issues, and a\n finding no longer raised is dismissed as RESOLVED. INVALID_ARGUMENT,\n before anything starts, when the check does not apply to the dataset\n (MIXTURE on an upload, EPISODE_RULES on a mixture, REACH on a dataset\n with no target robot, or one whose target robot is in another workspace,\n VLM when no selected episode has a published task) or the\n selection matches no episode. VLM is FAILED_PRECONDITION on a\n deployment with no VLM check pipeline. On a merged dataset VLM and REACH\n are one run over its own episodes, and the other\n checks run in each upload it holds, one run per upload, the selection\n split by upload; either way the findings are issues of the upload that\n holds each episode, named under the merged dataset. `model` chooses the\n VLM check's model; with `validate_only` nothing starts and the response\n carries the estimate.\n Each run is a CheckRun (`check_runs`): GetCheckRun says where it stands.\n A person's `checks/vlm` while a run of it is on the dataset (an automatic\n run after preparation, or a person's, running or\n queued) waits its turn: its run is recorded QUEUED behind the\n newest such run (`queued_behind`, `queued_reason`) and starts when that\n one ends, reserving only then. Runs queued on one dataset start in the\n order they were asked for. An estimate is never refused for a run in\n flight. A retry with the first call's request_id is answered with its\n receipt.\n\n `checks/reach` is the Run solver press, and it is recorded before the\n answer: the dataset's settings (reach_settings, else the target robot's\n defaults) and the robot's config make the run's key, every episode that\n already has a succeeded result under that key is answered from it (the\n other episodes, failed ones included, are queued), and the run, counted\n in ReachRun, is what GetReachStatus reports. The RunCheck operation ends\n when the work is queued; the run's own progress is the ReachRun. On a\n merged dataset the press is one run over all its episodes, every\n upload's, on its own settings. Succeeded results under its current full\n reach key answer it from storage; separate pre-merge TCP solves can\n have different calibration identities.\n FAILED_PRECONDITION, before anything is queued, on a server where the\n reach check is switched off (nothing would run the work), and for\n `checks/reach` when the target robot has no solver (there is no default\n one, and the dataset's own reach_settings do not give the robot one; a\n `validate_only` press is refused too).", "operationId": "Checks_RunCheck", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "check", "in": "path", "description": "The check id.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.RunCheckRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.RunCheckResponse" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/datasets": { "get": { "tags": [ "Datasets" ], "description": "Lists the datasets of one account (uploads, mixtures and merged datasets).\n An upload that was merged into another dataset (`merged_dataset` is set) is\n left out, unless the filter restricts `slug` to one value (`slug = \"...\"`),\n which is how a page finds a dataset by the name a version cites; `readers`\n to one mixture (`readers = \"...\"`), since a source can pin one of a\n merged-away upload's tags; or `merged_dataset` to one merged dataset,\n which lists the uploads it holds (its history).", "operationId": "Datasets_ListDatasets", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "At most this many datasets; 0 means 100, the maximum is 500.", "schema": { "type": "integer", "format": "int32" } }, { "name": "pageToken", "in": "query", "description": "From a previous response's next_page_token.", "schema": { "type": "string" } }, { "name": "filter", "in": "query", "description": "AIP-160 filter. A merged-away upload is left out unless `slug`, `readers`\n or `merged_dataset` is restricted to one value with `=` (see\n ListDatasets). Fields: kind\n (UPLOAD, MIXTURE or MERGED), state, labels.task, labels.robot,\n labels.operator, labels.method, tags (e.g. `tags : \"umi\"`),\n labels.methods (legacy alias for tags),\n labels.scene, source_robot, target_robot,\n linked_task (e.g. `linked_task = \"accounts/a/tasks/t\"`; `\"\"` for unlinked),\n robot_interface.interface_hash, create_time, update_time, slug, display_name (`:`\n substring), `merged_dataset` (the merged dataset that holds an upload, e.g.\n `merged_dataset = \"accounts/a/datasets/m\"`), and `reads` (datasets a\n mixture reads, e.g. `reads = \"accounts/a/datasets/b\"`), `readers`\n (datasets read by a mixture).", "schema": { "type": "string" } }, { "name": "orderBy", "in": "query", "description": "\"update_time desc\" (default), \"create_time\", \"display_name\", \"state\".", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.ListDatasetsResponse" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } }, "post": { "tags": [ "Datasets" ], "description": "Creates a mixture. Its sources are added with Mixtures.BatchCreateSources\n (several at once, resolved together) or Mixtures.CreateSource; a mixture\n with no sources reads nothing.", "operationId": "Datasets_CreateDataset", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "requestId", "in": "query", "description": "Idempotency key (AIP-155): a retry with the same id within 24 hours\n returns the first call's result instead of creating a second one.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.Dataset" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.Dataset" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/datasets/{dataset}": { "get": { "tags": [ "Datasets" ], "description": "Gets one dataset. Of a handheld upload it also says where its poses are\n (poses_at, poses_calibration), which List does not.", "operationId": "Datasets_GetDataset", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "dataset", "in": "path", "description": "The dataset id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.Dataset" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } }, "delete": { "tags": [ "Datasets" ], "description": "Deletes a mixture, or retires an upload or a merged dataset: it leaves\n every list and its episodes leave every mixture, but nothing is erased,\n and versions that pin its episodes keep resolving. A merged dataset is\n retired with the uploads it holds, which then answer\n NOT_FOUND; an upload bound to append to it that it does not hold (not\n appended yet, or taken back out before merges were final) is unbound.\n Refused with FAILED_PRECONDITION while another mixture reads it by name\n (for a merged dataset, also a pin of one of its uploads' tags; any other\n source left on one of them reads nothing and does not hold it); a\n mixture that reads it through a label source stops reading it. An upload\n merged into another is not deleted on its own (FAILED_PRECONDITION naming\n the merged dataset). A dataset whose episodes are references of Tasks\n (Dataset.task_references) is refused too unless sent with force, which\n removes those references.", "operationId": "Datasets_DeleteDataset", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "dataset", "in": "path", "description": "The dataset id.", "required": true, "schema": { "type": "string" } }, { "name": "etag", "in": "query", "description": "The dataset's current etag, when the caller wants the guard.", "schema": { "type": "string" } }, { "name": "force", "in": "query", "description": "Delete it even though its episodes are references of Tasks\n (Dataset.task_references), removing those references; the Tasks stay.\n Without it, such a dataset is refused (FAILED_PRECONDITION). Reingests\n and the ingest report live under uploads and are never deleted here.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": {} }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } }, "patch": { "tags": [ "Datasets" ], "description": "Edits display_name, description, labels, source_robot, target_robot or\n reach_settings. Emits DATASET_UPDATED (and TARGET_ROBOT_CHANGED for\n target_robot). Saving reach_settings starts nothing: the next RunCheck on\n `checks/reach` uses it, and until then the stored results stay as they are.\n A merged dataset's source_robot, target_robot and reach_settings are\n written to each upload it holds that differs (each records its own events;\n a source robot is the upload's explicit assignment). Its tags, labels,\n compatibility collection axes and linked_task are stored on C alone. An upload merged into another is written\n through it: any edit of one is FAILED_PRECONDITION naming the merged\n dataset.", "operationId": "Datasets_UpdateDataset", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "dataset", "in": "path", "description": "The dataset id.", "required": true, "schema": { "type": "string" } }, { "name": "updateMask", "in": "query", "description": "Which fields to change: display_name, description, tags (custom edits\n with unchanged derived classifications), labels (not a mixture),\n labels.methods (legacy six-method projection), source_robot (not a\n mixture), target_robot, reach_settings (replace as a whole), linked_task\n (not a mixture). A merged dataset's collection tags and labels are its\n own; source_robot, target_robot and reach_settings also change its uploads.\n \"*\", or no mask, preserves an absent/default empty repeated field; use\n the exact tags mask to deliberately clear customs. Change reserved\n classifications through their metadata paths instead.", "schema": { "type": "string", "format": "field-mask" } }, { "name": "humanMethodsOnly", "in": "query", "description": "With the exact labels.methods mask, replace only umi/teleop/egocentric\n on the selected dataset, preserving its other collection tags. The\n supplied methods must contain only that human subset; [] deliberately\n records Unknown and suppresses inference. Independent-axis aliases are\n retained through the canonical collection set. A merged dataset changes\n only its own tags. Clients must observe all three optional axis fields\n in a server reply before using this intent: older servers may ignore this\n flag and would treat the list as a full replacement.", "schema": { "type": "boolean" } }, { "name": "relinkEpisodes", "in": "query", "description": "With linked_task in the mask, on an upload or a merged dataset\n (the takes of every upload it holds): the takes that link the\n dataset's previous Task themselves drop that link and read the new one.\n Takes linking any other task keep their link. Without it, only the takes\n with no link of their own follow the change. Count them first with\n SummarizeEpisodes,\n `linked_task = \"\" AND linked_task_inherited = false`.", "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.Dataset" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.Dataset" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/datasets/{dataset}/cameraLags": { "get": { "tags": [ "Datasets" ], "description": "Reads per-camera lag estimates and current stamp offsets for an upload,\n or every upload held by a merged dataset. Untrusted estimates are reported\n but never applied implicitly.", "operationId": "Datasets_GetCameraLags", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "dataset", "in": "path", "description": "The dataset id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.CameraLags" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/datasets/{dataset}/checkPolicies/{checkPolicy}": { "get": { "tags": [ "Checks" ], "description": "Reads the effective policy and its source for each scheduler half.", "operationId": "Checks_GetAutomaticCheckPolicy_Dataset", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "dataset", "in": "path", "description": "The dataset id.", "required": true, "schema": { "type": "string" } }, { "name": "checkPolicy", "in": "path", "description": "The checkPolicy id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.AutomaticCheckPolicy" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } }, "patch": { "tags": [ "Checks" ], "description": "Updates only the selected halves; an inherit value removes that override.", "operationId": "Checks_UpdateAutomaticCheckPolicy_Dataset", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "dataset", "in": "path", "description": "The dataset id.", "required": true, "schema": { "type": "string" } }, { "name": "checkPolicy", "in": "path", "description": "The checkPolicy id.", "required": true, "schema": { "type": "string" } }, { "name": "updateMask", "in": "query", "description": "The halves to change: heuristic, graph, or both. Omitted halves stay put.\n A selected field set to SETTING_UNSPECIFIED clears its override.", "schema": { "type": "string", "format": "field-mask" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.AutomaticCheckPolicy" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.AutomaticCheckPolicy" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/datasets/{dataset}/checks": { "get": { "tags": [ "Checks" ], "description": "Lists the catalog's checks as one dataset sees them: every\n active check version, grouped by category in the order returned, each\n with whether it can run on this dataset now and its latest completed\n result here. A check that cannot run is listed with the reason, never\n left out. NOT_FOUND outside the caller's workspace.", "operationId": "Checks_ListDatasetChecks", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "dataset", "in": "path", "description": "The dataset id.", "required": true, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "At most this many; 0 means 100, the maximum is 1000.", "schema": { "type": "integer", "format": "int32" } }, { "name": "pageToken", "in": "query", "description": "From a previous response's next_page_token.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.ListDatasetChecksResponse" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/datasets/{dataset}/checks/{check}/findings": { "get": { "tags": [ "Checks" ], "description": "Lists the findings catalog checks wrote on a dataset, newest first: one\n per check, episode and finding key per run. The check may be `-` for\n every check's. Findings written before the catalog (templates)\n are listed under the check their template maps to, with `legacy` set.\n\n By default only the findings that stand: for each check and episode,\n those of the newest run of that check (by start) that read the episode\n at its linked revision, the Task and revision its link carries\n (Episode.linked_task_revision: its own link's, else its dataset's).\n Publishing a newer revision changes nothing; after a relink an episode\n has none until a run reads the new revision. A draft link carries no\n revision, nor does an episode with no link: there a finding stands while\n its Task is published at the revision it read (a draft's until the Task\n is first published), and one whose Task the workspace no longer has has\n no newer revision. Under any link only the linked Task's findings stand:\n a link moved to another Task, published or not, leaves none until a run\n reads that Task. A finding with no Task has no revision. A heuristic\n check has no Task revision: its findings are its issues, each as its\n newest run left it. The filter `all_revisions = true` lists every run's\n findings.", "operationId": "Checks_ListCheckFindings", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "dataset", "in": "path", "description": "The dataset id.", "required": true, "schema": { "type": "string" } }, { "name": "check", "in": "path", "description": "The check id.", "required": true, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "At most this many; 0 means 100, the maximum is 1000.", "schema": { "type": "integer", "format": "int32" } }, { "name": "pageToken", "in": "query", "description": "From a previous response's next_page_token.", "schema": { "type": "string" } }, { "name": "filter", "in": "query", "description": "AIP-160 filter. Fields: check_run, episode (names, `=`), verdict, and\n all_revisions (`true` lists superseded runs' findings too; default\n `false`: only the findings that stand). Terms join with AND.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.ListCheckFindingsResponse" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/datasets/{dataset}/checks:run": { "post": { "tags": [ "Checks" ], "description": "Runs catalog checks over a dataset as one run: the union of\n `check_ids`, `categories` and `all`, deduplicated, on the episodes of\n `selection`, sampled to `max_episodes`. The selection is resolved and\n pinned before the estimate (check versions, Task revisions, episodes),\n and the run reads exactly what was pinned. One model call per episode\n reads every selected VLM check. An episode a check cannot read (no\n published Task for a Task check) is skipped for that check, never\n passed. `all` and a category take the checks that can run and list the\n rest in `skipped_checks`. INVALID_ARGUMENT, before anything starts, for\n an empty selection, an unknown check id or category, a named check that\n cannot run on this dataset, a selection none of whose checks can run, or\n when no episode is eligible for any selected check;\n FAILED_PRECONDITION on a deployment with no checks runner, and, for a\n person's run, while a selected check is still running on this dataset:\n the message names that run, which DatasetCheck.running_check_run also\n lists. An estimate (`validate_only`) is answered either way. A retry with\n the first call's request_id is answered with its run, not refused. With\n `validate_only` nothing starts and nothing is reserved: the response\n carries the resolved selection and pipeline-api's bound for it, the\n same bound a run reserves. A run needs `max_cost` at or above that\n bound. Each run is a CheckRun under `checks/vlm`.", "operationId": "Checks_RunDatasetChecks", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "dataset", "in": "path", "description": "The dataset id.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.RunDatasetChecksRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.RunDatasetChecksResponse" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/datasets/{dataset}/episodes": { "get": { "tags": [ "Episodes" ], "description": "Lists the episodes of a dataset in recording order (for a mixture: its\n pool, source by source). `parent` may be `accounts/a/datasets/-` to read\n across every dataset of the account (ExploreLake's successor).", "operationId": "Episodes_ListEpisodes", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "dataset", "in": "path", "description": "The dataset id.", "required": true, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "At most this many episodes; 0 means 100, the maximum is 1000.", "schema": { "type": "integer", "format": "int32" } }, { "name": "pageToken", "in": "query", "description": "From a previous response's next_page_token.", "schema": { "type": "string" } }, { "name": "filter", "in": "query", "description": "AIP-160 filter. e.g. `state = UNREVIEWED AND open_issue_codes:\"jerky\"`,\n `note_codes:\"graph_outcome\"`, `methods:\"umi\"`, `version = \"1.0\"`,\n `metrics.duration_seconds < 20`,\n `viewed = false`, `linked_task_inherited = false`, `draft = true`\n (takes with a draft, Episode.draft).", "schema": { "type": "string" } }, { "name": "orderBy", "in": "query", "description": "\"index\" (default: recording order, source by source in a mixture),\n \"record_time\", \"metrics. desc\", \"open_issue_count desc\".", "schema": { "type": "string" } }, { "name": "view", "in": "query", "description": "EPISODE_VIEW_ANALYSIS adds each episode's Episode.analysis, its\n channels' progress only: a channel's curves are GetEpisode's. It signs\n no posters (Episode.posters is empty): a reader of every take's profile\n shows few posters, and reads those with GetEpisode.", "schema": { "enum": [ "EPISODE_VIEW_UNSPECIFIED", "EPISODE_VIEW_BASIC", "EPISODE_VIEW_ANALYSIS" ], "type": "string", "format": "enum" } }, { "name": "version", "in": "query", "description": "Read as this version froze it: a tag, `stable`, `v0` or a\n digest prefix; empty or `head` reads the episode as it is now. The list\n holds that version's episodes, each with the fields, trim and subtasks of\n the revision it pinned (task and tags as its snapshot froze them, also\n for an episode never edited); standing, decision, issues and markers are\n current. A version the dataset does not have is NOT_FOUND.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.ListEpisodesResponse" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/datasets/{dataset}/episodes/{episode}": { "get": { "tags": [ "Episodes" ], "description": "Gets one episode as its parent dataset sees it.", "operationId": "Episodes_GetEpisode", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "dataset", "in": "path", "description": "The dataset id.", "required": true, "schema": { "type": "string" } }, { "name": "episode", "in": "path", "description": "The episode id.", "required": true, "schema": { "type": "string" } }, { "name": "view", "in": "query", "description": "EPISODE_VIEW_ANALYSIS adds Episode.analysis with every channel's\n autocorrelation and alignment curves.", "schema": { "enum": [ "EPISODE_VIEW_UNSPECIFIED", "EPISODE_VIEW_BASIC", "EPISODE_VIEW_ANALYSIS" ], "type": "string", "format": "enum" } }, { "name": "version", "in": "query", "description": "Read as this version froze it: a tag, `stable`, `v0` or a\n digest prefix; empty or `head` reads the episode as it is now. Its\n fields, trim and subtasks are the revision that version pinned (task and\n tags as its snapshot froze them; markers are current), and `revision` and\n `etag` name it, so an edit sent with them is refused once the episode has\n moved on. NOT_FOUND when the version does not hold it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.Episode" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } }, "patch": { "tags": [ "Episodes" ], "description": "Deprecated: use UpdateEpisodes with one edit, which this now runs. Kept for one release for clients built before it.\n Edits task, instruction, method, methods, scene, tags or outcome, which\n writes one episode revision and emits EPISODE_EDITED, or draws trim or\n subtasks on the take's draft, as UpdateEpisodes does. Edits are the\n take's own and read the same from every scope.", "operationId": "Episodes_UpdateEpisode", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "dataset", "in": "path", "description": "The dataset id.", "required": true, "schema": { "type": "string" } }, { "name": "episode", "in": "path", "description": "The episode id.", "required": true, "schema": { "type": "string" } }, { "name": "updateMask", "in": "query", "description": "Which fields to change: task, instruction, method, methods, scene, tags,\n outcome, trim, subtasks. Use methods to explicitly replace or clear tags;", "schema": { "type": "string", "format": "field-mask" } }, { "name": "requestId", "in": "query", "description": "Optional UUID4 identifying this logical edit. Reusing it with the same\n caller and request returns the original result; different input conflicts.\n When absent, each call starts a new logical edit.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.Episode" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.Episode" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/datasets/{dataset}/episodes/{episode}/draft": { "get": { "tags": [ "Episodes" ], "description": "The take's draft, through any dataset that reads the take. NOT_FOUND\n when it has none.", "operationId": "Episodes_GetEpisodeDraft", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "dataset", "in": "path", "description": "The dataset id.", "required": true, "schema": { "type": "string" } }, { "name": "episode", "in": "path", "description": "The episode id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.EpisodeDraft" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } }, "delete": { "tags": [ "Episodes" ], "description": "Discards the take's draft. Idempotent when it has none. Refused as\n UpdateEpisodeDraft refuses.", "operationId": "Episodes_DeleteEpisodeDraft", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "dataset", "in": "path", "description": "The dataset id.", "required": true, "schema": { "type": "string" } }, { "name": "episode", "in": "path", "description": "The episode id.", "required": true, "schema": { "type": "string" } }, { "name": "etag", "in": "query", "description": "When set, refuses (ABORTED) if the draft changed since it was read.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": {} }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } }, "patch": { "tags": [ "Episodes" ], "description": "Saves the take's draft as drawn: replaces the drawing and its base, or\n creates the draft (allow_missing). The person holding the take's live\n edit lease saves it, and so does any caller with write access, a person\n or an API key, while no other person holds one; another person's live\n lease is FAILED_PRECONDITION, naming them. A stale etag is ABORTED (read\n the draft again); a drawing past the bounds is INVALID_ARGUMENT. Nothing\n is applied: the dataset's head keeps the take as it is.", "operationId": "Episodes_UpdateEpisodeDraft", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "dataset", "in": "path", "description": "The dataset id.", "required": true, "schema": { "type": "string" } }, { "name": "episode", "in": "path", "description": "The episode id.", "required": true, "schema": { "type": "string" } }, { "name": "allowMissing", "in": "query", "description": "Create the draft when the take has none; without it, NOT_FOUND.", "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.EpisodeDraft" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.EpisodeDraft" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/datasets/{dataset}/episodes/{episode}/revisions": { "get": { "tags": [ "Episodes" ], "description": "An episode's edits, newest first, then the recording as revision 0; an\n episode nobody edited lists nothing. The history is the take's: the same\n through any dataset that holds it.", "operationId": "Episodes_ListEpisodeRevisions", "parameters": [ { "name": "account", "in": "path", "description": "The account id.", "required": true, "schema": { "type": "string" } }, { "name": "dataset", "in": "path", "description": "The dataset id.", "required": true, "schema": { "type": "string" } }, { "name": "episode", "in": "path", "description": "The episode id.", "required": true, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "At most this many; 0 means 50, the maximum is 500.", "schema": { "type": "integer", "format": "int32" } }, { "name": "pageToken", "in": "query", "description": "From a previous response's next_page_token.", "schema": { "type": "string" } }, { "name": "revisions", "in": "query", "description": "Optional exact revisions (at most two, nonnegative). Cannot be combined\n with page_token. Missing revisions are omitted, never replaced by head.", "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/qualia.v1.ListEpisodeRevisionsResponse" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google.rpc.Status" } } } } } } }, "/v1/accounts/{account}/datasets/{dataset}/episodes/{episode}:acquireEpisodeLease": { "post": { "tags": [ "Episodes" ], "description": "Takes the take's edit lease for the caller and this tab. A\n lease is per take: it holds through every dataset that reads it. One\n lease per person: when the caller already holds it, the tab joins it and\n it is renewed. It lapses 30 s after the last renewal. FAILED_PRECONDITION,\n \"episode is being edited by until