Lab

Executes a PassQL read query over the Lab read model and returns a columns/rows result with a freshness watermark. Send the compiled ast; optionally include the dsl_text it came from, which is stored on the resulting run for display. Requires lab:read.

A query that fails validation or compilation returns 422 with the error envelope, whose error.errors names the offending AST stages. A query naming an ontology that is not your team's is 403 forbidden_ontology; one that exceeds the statement timeout is 408 query_timeout — narrow the filter, reduce the page size, or use an export.

Required attributes

Optional attributes

Paging a query

Row-mode results page inside the AST, not by query parameter: ast.limit is the page size and ast.cursor takes the previous response's next_cursor. Keep going until next_cursor is null. The PassQL grammar has no cursor clause, so add the field to the parsed AST yourself.

This is a different mechanism from the limit/cursor pagination the list endpoints use: a Lab query cursor is a plain keyset token rather than an encrypted, scope-bound one, and a malformed or stale one fails with 422 bad_cursor rather than 400 invalid_cursor.

Translated values

Text-bearing properties hold a value per language, and a property reference reads exactly one of them. With nothing specified it is each ontology's own default language, which is what an existing query has always matched. from … lang:"de" moves the whole pipeline to German, and p"Description"@"de" pins one reference, overriding the pipeline. A passport with no translation in the requested language reads as empty for that reference — there is no fallback. In the AST these are source.lang and a reference's prop.lang, each one of the 24 official EU language codes; any other value fails validation naming that path. See PassQL.

Compile-checks an ast without executing it — the fast way to confirm a query is well formed before you run or preview it. Requires lab:read.

A valid AST answers {"valid": true, "mode": …} with the mode it would produce. A failure is the standard error envelope at whatever status the underlying failure carries — 422 with the offending stages in error.errors for an invalid or uncompilable AST, but 403 forbidden_ontology when the query names another team's ontology. Branch on error.code, not on the status.

Required attributes

Parses PassQL source text into the ast the other endpoints consume, resolving ontology names in the from clause to ontology ids along the way. This is the usual way to obtain an AST outside the Blocks builder: write PassQL, parse it, then hand the AST to run, validate, or preview. Requires lab:read.

Invalid input returns 422 with error.param set to dsl_text and one of four codes: query_empty (blank dsl_text), parse_error (unparseable PassQL), unknown_ontology (no ontology of that name in the team) or ambiguous_ontology (the name matches more than one — errors[].expected lists the candidate ids). Each row of error.errors carries a message, a byte offset, a length, and what was expected; offset and length are null for an ontology name that cannot be resolved, which is not tied to a token position.

Required attributes

The inverse of parse: renders an ast back into canonical PassQL text. Useful for showing a Blocks-built query as source, or for round-tripping a machine-built AST into something readable. Requires lab:read.

A body that is not an AST object is 422 invalid_ast; an AST that cannot be represented in PassQL is 422 unprintable_ast. Neither is positional, so error.errors is omitted.

Required attributes

Dry-runs a transform — a query whose AST carries a set stage — and returns its projected impact (how many passports it would change, plus up to 20 sampled before/after pairs) together with a preview_id. Nothing is written. You must pass that preview_id back to execute within 15 minutes; after that it expires.

Requires lab:write, plus releases:write when the transform assigns publish_status, and your team must be on the deployment's transform allowlist — otherwise 403 transforms_not_enabled. See PassQL's | set stage for how to build a transform AST.

A body that is not an AST object is 422 invalid_ast; a PassQL failure inside a well-formed AST is a compile error with the offending stages in error.errors.

Transforms and releases

set publish_status = "released" (or "draft", "archived", or null to clear the explicit status) is applied per passport under the same release rules as PATCH /v1/passports/{passport}. A transform releases exactly the passports it selected and never cascades. A passport whose ancestor is not released, a value write on a released passport, and a move from released to archived are refused for that passport alone: it is left untouched, recorded as a conflict on the run's changes, and the run carries on.

Required attributes

The preview

Executes a transform you have just previewed. Pass the same ast along with the preview_id you were handed; if the preview has expired or no longer matches the AST, the call fails with 409 preview_mismatch — so you always confirm a fresh impact before anything is written. Values are recomputed from live passport data at apply time, and the run proceeds asynchronously: it returns 201 with a run_id you poll via retrieve a run.

Requires lab:write, plus releases:write when the transform assigns publish_status — the same gating as preview. A missing or malformed ast or preview_id is 422 parameter_invalid, with error.param naming whichever failed. Accepts an optional Idempotency-Key header.

Required attributes

Optional attributes

Lists your team's Lab runs — queries, transforms, rollbacks, backfills and exports — newest first. Returns a paginated list of run objects; drive it with has_more and next_cursor rather than assuming one request returns everything. Requires lab:read.

Optional attributes

Retrieves one run by its integer run id. Poll this after executing a transform, rollback or export until status reaches a terminal value — complete, partial, or failed (the counts break down what applied, failed, or conflicted). Requires lab:read.

Lists the individual property changes a transform or rollback recorded — one record per property per passport, each with the passport_snowflake, the property_id, the old_value/new_value, its status, and an error when the row failed or conflicted. Records are raw rows rather than a wrapped resource: no object and no id. Requires lab:read.

A transform over a large ontology produces far more of these than fit in one page, so this is a paginated list ordered by passport, then by property — walk has_more, or you will believe you have seen every change. status narrows the result set and therefore joins the cursor's scope: a cursor from the unfiltered walk replayed with a filter is 400 invalid_cursor.

Two property_id values are reserved and are not property ids: __error (the run could not evaluate the set-expression for that passport at all — one row per passport, status failed) and publish_status (the run assigned the passport's explicit publish status). Treat any property_id beginning with __ as reserved.

Optional attributes

Queues a rollback of a transform, restoring every applied change to its recorded old_value. Only the team's latest finished, non-rolled-back transform is eligible — status complete or partial — and anything else returns 409 not_rollback_eligible, so check rollback_eligible on the run first. A run can be rolled back at most once: concurrent requests are resolved atomically, so exactly one is queued and the rest get 409 not_rollback_eligible.

Like executing a transform, this runs asynchronously, returns 201 with the new rollback run's id, and requires lab:write and the transform allowlist — plus releases:write when the run being rolled back assigned publish_status, since reversing it is a release transition too. Poll the returned run to completion.

Returns your team's Lab footprint over the last 30 days — how much read-model storage it occupies and an accounting of runs by type, including the passport-store capacity (rcu, wcu) transforms consumed. Queries report zero. Requires lab:read.

The storage snapshot is recomputed when the last one is over a day old, so captured_at may trail the request. cache_hit_ratio is null when no queries ran in the window.

Turns Lab on for the team. Requires lab:write — the ability transforms and rollbacks already carry, so it introduces no new concept. A key whose owner's role does not grant it is refused with 403 insufficient_permissions; re-issuing the key with more abilities does not help, because a key is capped by its owner's current permissions. The transform allowlist does not apply here: enabling Lab is not a mutation of anyone's data.

It does mean a first-run automation can provision Lab and query it without a human ever opening the console, which is the point of having the endpoint at all.

Enabling queues a backfill that mirrors the team's existing passports into the read model. Until it finishes, queries still answer — just from a partially warm index, which is indistinguishable from a genuinely small result set unless you check. The watermark, reported both on /v1/lab/meta and on every query result, is how you tell how far it has got; the response's backfill is the run to poll while you wait.

Enabling is idempotent. Calling it on an already-enabled team reports the current state, queues nothing, and emits no second event — and it reports the most recent backfill, so a caller that lost track can poll the run already in flight rather than starting a duplicate. It answers 200 with a lab.status object: Lab is a state of the team, not an object this call brings into existence.

Emits lab.enabled on the change feed.

Opts back out and purges the team's rows from the read model. Requires lab:write, exactly as enabling does.

That is destructive to the Lab index only: the passports it mirrors are untouched, and the run ledger is kept as history — GET /v1/lab/runs still answers after a disable. Re-enabling therefore rebuilds from source rather than restoring, which is why backfill is always null on a disable response — the backfill that warmed the index is about to be purged along with it.

Disabling is idempotent in the same way enabling is: on a team that is already disabled it reports the current state, purges nothing, and emits no second event. Emits lab.disabled on the change feed.

The ontology → depth → property catalog a client needs to author PassQL against this team, alongside the read model's watermark. Requires lab:read.

Without it a client has only two options, both bad: hard-code the vocabulary and break when a schema moves, or discover it by trial and error against query/validate.

Each ontology carries its id as ontology (not ontology_id) and the name a PassQL from clause matches on. Each depth carries its level key as depth, a name, and the properties you can query on it — id, name, type and unit, where unit is null for a property that has none. A versioned ontology reports the depths of its published graph.

Category properties are omitted. They exist to group other properties in the UI and are not queryable columns, so a catalog that listed them would be offering you names that cannot appear in a select or a where.

Queues a new run, of type export, that re-executes the source run's query and materializes the result as a file — csv by default, or xlsx if you ask for it. Because the AST is re-executed rather than replayed, the export reflects the data as of the export, not as of the original query.

It is lab:read, not lab:write — which reads like a mistake until you see why. An export materializes exactly what POST /v1/lab/query already returns to the same key. It creates no data and changes none; requiring a write ability would gate a read behind a write for no gain.

Only query runs can be exported. Point it at a transform, rollback, backfill or export run and you get 409 not_exportable rather than a 404 — the distinction is deliberate: the run exists and you are allowed to read it, it just is not the kind of thing that can be exported. A run belonging to another team, or no run at all, is 404 resource_missing.

An export is a read, and reads are not logged — it emits no event, matching what the application does. If you need a record that data left the platform in bulk, the run ledger is where it lives — GET /v1/lab/runs lists every export run, who queued it and when.

Optional attributes

Returns a short-lived presigned URL, not the bytes, on exactly the same terms as GET /v1/files/{file}/download. Requires lab:read.

No Authorization header is needed to fetch it, so treat the URL as a bearer credential for that one object until expires_at — 15 minutes by default. expires_at is absolute, so you can hold the URL for its lifetime rather than re-requesting it per download.

An export still being written is 409 export_not_ready, not a 404 — the run is real, the file simply is not there yet, so poll the run until it completes rather than retrying the download blindly. A run that is not an export at all reads as 404 resource_missing.