Save a dataset def — a persisted query over the episode lake

POST

/v1/datasets/defs

curl --request POST \
  --url https://example.com/v1/datasets/defs \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "name": "example", "description": "", "query": { "dataset_ids": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "task": "example", "tier": "", "min_duration_s": 1, "max_duration_s": 1, "tags": [ "example" ], "review_state": "", "search": "example", "numeric_predicates": [ { "field": "duration_s", "op": "gt", "value": 1 } ], "predicates": [ { "stream": "action", "channel": "example", "agg": "max", "op": "gt", "value": 1 } ], "episodes": [ { "dataset_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "episode_index": 1 } ], "query_text": "example" } }'

ADR 0010: a dataset is a saved query. Both modes land here — an exact selection (query.episodes, the pairs the user picked) and a dynamic view (the facets, resolved fresh at every pin). Pin the returned def to freeze a reproducible version.

Authorizations

• ApiKey
• Bearer

Parameters

Query Parameters

account_id

Act on this account (active)

string | null format: uuid

Act on this account (active)

Request Body ^required

Media type application/json

DatasetDefBody

Save a query over the episode lake as a dataset definition.

object

name

required

string

>= 1 characters <= 128 characters

description

string

"" <= 4096 characters

query

SavedQueryBody

ADR 0010: a dataset IS this query.

Closed and fully typed on purpose. The query travels to QDS as opaque JSON, so this model is the only place its shape is checked — an unmodelled key would be stored or dropped in silence and the definition would then resolve to a different set of episodes than the one the user built. Predicates reuse the explore bodies so a definition can only hold a filter the resolver can actually evaluate.

Quality is not expressible here: no status/flag facet exists, because selection is intent. Every episode a user picked belongs to the dataset, flagged ones included.

object

dataset_ids

Array<string>

<= 4096 items

task

string | null

tier

string

nullable

Allowed values: "" retrainable analyze_only

min_duration_s

number | null

max_duration_s

number | null

tags

Array<string>

<= 512 items

review_state

string

nullable

Allowed values: "" unreviewed auto_accepted human_audited rejected

search

string | null

numeric_predicates

Array<object>

<= 32 items

NumericPredicateBody

object

field

required

string

Allowed values: duration_s frame_count quality_score speed_mean jerk_mean frozen_action_dims action_dims frozen_state_dims state_dims sync_skew_max_ms sync_skew_ratio sparc ldlj psd_hf_ratio speed_p10 speed_p50 speed_p90 pause_fraction pause_count dt_jitter_ms dt_dropped_frames

op

required

string

Allowed values: gt lt gte lte

value

required

number

predicates

Array<object>

<= 32 items

ChannelPredicateBody

object

stream

string

default: action

Allowed values: action state telemetry

channel

required

string

agg

required

string

Allowed values: max min mean std

op

required

string

Allowed values: gt lt gte lte

value

required

number

episodes

Array<object>

<= 10000 items

SavedQueryEpisodeBody

One hand-picked member, keyed the way the server keys membership: (source dataset, episode index) — not an episode-row uuid.

object

dataset_id

required

string format: uuid

episode_index

required

integer

<= 2147483647

query_text

string | null

Responses

200

Successful Response

Media type application/json

Example ^generated

example

401

Invalid or missing API key

Media type application/json

ErrorResponse

Standard error response.

object

detail

required

Error message describing what went wrong

string

Example ^generated

{
  "detail": "example"
}

422

Unmodelled or oversized query

Media type application/json

ErrorResponse

Standard error response.

object

detail

required

Error message describing what went wrong

string

Example ^generated

{
  "detail": "example"
}