Reference

Products API

Every Qirava data operation is a small, named function reachable over one HTTP surface. This reference is generated from the running DMS itself: at build time the site constructs a real qdms runtime and reads its served /api/spec catalog, so what you see here is exactly what the server answers — there is no second list to drift.

Surface

The HTTP surface

Two discovery endpoints describe the whole API; every operation below is invoked through the single execute path behind a worker. The catalog is generated once at boot and served verbatim — it reads no row data and reflects no request body.

GET/api/specThe live JSON catalog this page is built from.

GET/api/spec/openapiThe same catalog as an OpenAPI 3.1 document.

Contract

The response envelope

Every call returns the same uniform envelope: a success carries data, an error carries a stable code and message, and both carry timing and a request id in root.

// success
{
    "error": null,
      "data": "<value>",
      "root": { "took_us": "<int>", "request_id": "<string>" }
  }

// error
{
    "error": { "code": "<stable_code>", "message": "<string>" },
      "data": null,
      "root": { "took_us": "<int>", "request_id": "<string>" }
  }

Contract

Stable error codes

There are eight stable error codes, each mapped to one HTTP status. They are the single source of truth for failure handling — every function documents the subset it can return.

Stable code	HTTP status
`ok`	200
`workers_busy`	503
`not_found`	404
`forbidden`	403
`bad_request`	400
`rate_limited`	429
`function_failed`	422
`internal`	500

Catalog

Functions

The complete function catalog, grouped by category. Each entry shows its key, access scope, origin, FIFO ordering, input and output fields, and the error codes it may return. Expand a row for the full detail.

Planner#

Parse and plan a QQL statement — the only door to a read or mutate.

qql.planner.queryParse and normalize a QQL query into a canonical plan.publicbuiltin

Runs the query planner's parse/normalize stage on the supplied QQL request and returns the canonical query plan without executing it.

Input

Field	Type
`query`	`string`	required
`params`	`record`	optional

Output

Field	Type
`plan`	`record`	required

Errors:bad_requestfunction_failedinternal

qql.planner.readPlan a read access path for a QQL query.publicbuiltin

Produces the read access path (index/scan choice) for the supplied query without reading any rows.

Input

Field	Type
`query`	`string`	required
`params`	`record`	optional

Output

Field	Type
`plan`	`record`	required

Errors:bad_requestfunction_failedinternal

Read#

Key, filter, sort, limit, join, and aggregate read paths.

qql.read.keyFetch a single row by primary key.publicbuiltin

Plans the query and fetches the row whose primary key matches the request, returning at most one row.

Input

Field	Type
`query`	`string`	required
`key`	`string`	required

Output

Field	Type
`rows`	`list<record>`	required
`count`	`int`	required

Errors:bad_requestfunction_failedinternal

qql.read.filterRead rows matching a predicate filter.publicbuiltin

Plans the query then applies a predicate filter, returning the matched rows.

Input

Field	Type
`query`	`string`	required
`params`	`record`	optional

Output

Field	Type
`rows`	`list<record>`	required
`count`	`int`	required

Errors:bad_requestfunction_failedinternal

qql.read.sortRead rows in sorted order.publicbuiltin

Plans the query and returns the matched rows sorted by the requested key.

Input

Field	Type
`query`	`string`	required
`sort`	`string`	optional

Output

Field	Type
`rows`	`list<record>`	required
`count`	`int`	required

Errors:bad_requestfunction_failedinternal

qql.read.limitRead rows with a row-count limit.publicbuiltin

Plans the query and returns at most `limit` matched rows.

Input

Field	Type
`query`	`string`	required
`limit`	`int`	optional

Output

Field	Type
`rows`	`list<record>`	required
`count`	`int`	required

Errors:bad_requestfunction_failedinternal

qql.read.filter_sort_ascFilter, ascending-sort, and limit rows in one path.publicbuiltin

Normalizes and plans a combined filter + ascending sort + limit access path and returns the matched rows.

Input

Field	Type
`query`	`string`	required
`filter`	`record`	optional
`sort`	`string`	optional
`limit`	`int`	optional

Output

Field	Type
`rows`	`list<record>`	required
`count`	`int`	required

Errors:bad_requestfunction_failedinternal

qql.read.joinRead rows joined with a related table.publicbuiltin

Plans the query and joins the matched rows against a related table, returning the combined rows.

Input

Field	Type
`query`	`string`	required
`join`	`record`	required

Output

Field	Type
`rows`	`list<record>`	required
`count`	`int`	required

Errors:bad_requestfunction_failedinternal

qql.read.aggregateAggregate matched rows.publicbuiltin

Plans the query and returns aggregate results (e.g. counts/sums) over the matched rows.

Input

Field	Type
`query`	`string`	required
`aggregate`	`record`	required

Output

Field	Type
`groups`	`list<record>`	required

Errors:bad_requestfunction_failedinternal

qql.read.join_aggregateJoin a related table then aggregate.publicbuiltin

Plans the query, joins a related table, and returns aggregate results over the joined rows.

Input

Field	Type
`query`	`string`	required
`join`	`record`	required
`aggregate`	`record`	required

Output

Field	Type
`groups`	`list<record>`	required

Errors:bad_requestfunction_failedinternal

Write#

Insert, update, upsert, delete, schema upgrade, and shard move. All FIFO-ordered.

qql.write.insertInsert new rows.publicbuiltinfifo

Plans the write, stages an insert, then prepares, applies, and commits it through the WAL.

Input

Field	Type
`table`	`string`	required
`rows`	`list<record>`	required

Output

Field	Type
`committed`	`bool`	required
`affected`	`int`	required

Errors:bad_requestrate_limitedfunction_failedworkers_busyinternal

qql.write.updateUpdate existing rows.publicbuiltinfifo

Plans the write, stages an update over matched rows, then commits it through the WAL.

Input

Field	Type
`table`	`string`	required
`filter`	`record`	required
`set`	`record`	required

Output

Field	Type
`committed`	`bool`	required
`affected`	`int`	required

Errors:bad_requestrate_limitedfunction_failedworkers_busyinternal

qql.write.upsertInsert or update rows by key.publicbuiltinfifo

Plans the write, stages an upsert (insert-or-update by primary key), then commits it through the WAL.

Input

Field	Type
`table`	`string`	required
`rows`	`list<record>`	required

Output

Field	Type
`committed`	`bool`	required
`affected`	`int`	required

Errors:bad_requestrate_limitedfunction_failedworkers_busyinternal

qql.write.deleteDelete rows matching a filter.publicbuiltinfifo

Plans the write, stages a delete over matched rows, then commits it through the WAL.

Input

Field	Type
`table`	`string`	required
`filter`	`record`	required

Output

Field	Type
`committed`	`bool`	required
`affected`	`int`	required

Errors:bad_requestrate_limitedfunction_failedworkers_busyinternal

qql.write.upgradeApply a schema upgrade.publicbuiltinfifo

Plans the write, stages a schema upgrade for a table, then commits it through the WAL.

Input

Field	Type
`table`	`string`	required
`schema`	`record`	required

Output

Field	Type
`committed`	`bool`	required
`affected`	`int`	required

Errors:bad_requestrate_limitedfunction_failedworkers_busyinternal

qql.write.moveMove a shard.publicbuiltinfifo

Plans the write, stages a shard move, then commits it through the WAL.

Input

Field	Type
`shard`	`string`	required
`target`	`string`	required

Output

Field	Type
`committed`	`bool`	required
`affected`	`int`	required

Errors:bad_requestrate_limitedfunction_failedworkers_busyinternal

Search#

Full-text scoring, with an optional post-filter.

qql.search.textScore a full-text query.publicbuiltin

Plans the query then scores matching rows against the full-text term, returning ranked hits.

Input

Field	Type
`query`	`string`	required
`text`	`string`	required

Output

Field	Type
`hits`	`list<record>`	required
`count`	`int`	required

Errors:bad_requestfunction_failedinternal

qql.search.filterFull-text search with a post-filter.publicbuiltin

Plans the query, scores full-text hits, then applies a predicate filter to the ranked hits before returning them.

Input

Field	Type
`query`	`string`	required
`text`	`string`	required
`filter`	`record`	optional

Output

Field	Type
`hits`	`list<record>`	required
`count`	`int`	required

Errors:bad_requestfunction_failedinternal

Graph#

Resolve a node, traverse edges, and resolve a path between nodes.

qql.graph.nodeResolve a graph start node.publicbuiltin

Plans the query and resolves the start node it identifies, returning the matched node.

Input

Field	Type
`query`	`string`	required
`node`	`string`	required

Output

Field	Type
`node`	`record`	required

Errors:bad_requestfunction_failedinternal

qql.graph.traverseTraverse edges from a start node.publicbuiltin

Plans the query, resolves the start node, then traverses adjacent edges, returning the reached nodes.

Input

Field	Type
`query`	`string`	required
`node`	`string`	required
`depth`	`int`	optional

Output

Field	Type
`nodes`	`list<record>`	required
`count`	`int`	required

Errors:bad_requestfunction_failedinternal

qql.graph.pathResolve a path between two nodes.publicbuiltin

Plans the query, resolves the start node, traverses edges, and returns a path to the requested target node.

Input

Field	Type
`query`	`string`	required
`from`	`string`	required
`to`	`string`	required

Output

Field	Type
`path`	`list<record>`	required
`count`	`int`	required

Errors:bad_requestfunction_failedinternal

Vector#

Approximate nearest-neighbor search, optionally filtered.

qql.vector.knnApproximate nearest-neighbor search.publicbuiltin

Plans the query and returns the approximate `k` nearest neighbors to the request vector.

Input

Field	Type
`query`	`string`	required
`vector`	`list<float>`	required
`k`	`int`	optional

Output

Field	Type
`hits`	`list<record>`	required
`count`	`int`	required

Errors:bad_requestfunction_failedinternal

qql.vector.filteredFiltered approximate nearest-neighbor search.publicbuiltin

Plans the query, computes the nearest neighbors, then applies a predicate filter to the candidates before returning them.

Input

Field	Type
`query`	`string`	required
`vector`	`list<float>`	required
`k`	`int`	optional
`filter`	`record`	optional

Output

Field	Type
`hits`	`list<record>`	required
`count`	`int`	required

Errors:bad_requestfunction_failedinternal

Inline#

Composed, concurrent fan-outs that span several access paths in one call.

qql.inline.read_searchConcurrent read + full-text + graph fan-out.publicbuiltin

Runs a filtered read, a full-text search, and a graph node lookup concurrently over the same input and returns their combined results.

Input

Field	Type
`query`	`string`	required
`params`	`record`	optional

Output

Field	Type
`results`	`list<record>`	required

Errors:bad_requestfunction_failedinternal

qql.inline.join_aggregate_vectorJoin then concurrent aggregate + vector fan-out.publicbuiltin

Plans and joins a related table, then concurrently aggregates the joined rows and runs vector KNN + filter over them, returning the combined results.

Input

Field	Type
`query`	`string`	required
`join`	`record`	required
`vector`	`list<float>`	optional

Output

Field	Type
`results`	`list<record>`	required

Errors:bad_requestfunction_failedinternal

Auth & governance#

Sessions, signed keys, API keys, and the deny-by-default RBAC before-chain.

auth.loginHuman login: exchange credentials for a session token.publicbuiltin

Verifies `{username, password}` against `_sys_users` (PBKDF2), mints a random session token, stores only its hash in `_sys_sessions`, and returns the plaintext token once. No role gate.

Input

Field	Type
`username`	`string`	required
`password`	`string`	required

Output

Field	Type
`token`	`string`	required
`user`	`string`	required
`role`	`string`	required
`expires_us`	`int`	required

Errors:bad_requestforbiddeninternal

auth.session`before` gate: validate a session bearer token.publicbuiltin

Looks up the bearer token's hash in `_sys_sessions`, rejects expired/absent/disabled sessions, optionally enforces a required role, and injects `{user, role}`. Denies with `forbidden`.

Input

Field	Type
`authorization`	`string`	required
`required_role`	`string`	optional

Output

Field	Type
`user`	`string`	required
`role`	`string`	required

Errors:bad_requestforbidden

auth.session_extend`after` hook: bump the session idle window on success.publicbuiltin

On a successful authenticated request, extends the session's `expires_us` by the idle window. Read-only w.r.t. the response; never fails the request.

Input

Field	Type
`authorization`	`string`	optional

Output

Field	Type
`extended`	`bool`	required

Errors:

auth.signed`before` gate: verify a stateless signed API-key request.publicbuiltin

Verifies the HMAC over the canonical request string, checks timestamp skew and nonce replay, and injects the key's scope + table grants. Denies with `forbidden`.

Input

Field	Type
`x-key-id`	`string`	required
`x-timestamp`	`string`	required
`x-nonce`	`string`	required
`x-signature`	`string`	required

Output

Field	Type
`api_key_scope`	`string`	required
`table_grants`	`string`	required

Errors:bad_requestforbidden

auth.api_key`before` gate: validate an API key against `_sys_api_keys`.publicbuiltin

Hashes the `X-API-Key` (or bearer) value, looks up the enabled key in `_sys_api_keys`, and injects its scope + table grants. Denies with `forbidden` when missing or invalid.

Input

Field	Type
`x-api-key`	`string`	optional
`authorization`	`string`	optional

Output

Field	Type
`api_key_scope`	`string`	required
`table_grants`	`string`	required

Errors:bad_requestforbidden

auth.create_api_keyMint an API key (admin scope); returns the plaintext once.publicbuiltin

Generates a random key, stores only its SHA-256 hash plus scope/grants in `_sys_api_keys`, and returns the plaintext key once. Non-admin keys require a valid table-grant CSV.

Input

Field	Type
`scope`	`string`	optional
`grants`	`string`	optional

Output

Field	Type
`api_key`	`string`	required
`key_id`	`string`	required
`sign_secret`	`string`	required
`scope`	`string`	required
`table_grants`	`string`	required

Errors:bad_requestforbiddeninternal

auth.check_table_grant`before` gate: deny-by-default table-level RBAC for a QQL stmt.publicbuiltin

Parses the request's QQL and, using the key's scope + table grants, allows or denies the statement DENY-BY-DEFAULT (admin keys bypass). Denies with `forbidden`.

Input

Field	Type
`qql`	`string`	optional
`api_key_scope`	`string`	optional
`table_grants`	`string`	optional

Output

Field	Type
`granted`	`bool`	required

Errors:bad_requestforbidden

auth.grant_tableGrant/revoke a table on an existing API key (admin).publicbuiltin

Updates an existing key's table-grant CSV (sorted); `grant = "none"` revokes. Re-serializes and UPDATEs the key row.

Input

Field	Type
`key_id`	`string`	required
`table`	`string`	required
`grant`	`string`	required

Output

Field	Type
`success`	`bool`	required
`table`	`string`	required
`grant`	`string`	required
`table_grants`	`string`	required

Errors:bad_requestforbiddeninternal

auth.create_userCreate a user or guest (role-gated: admin or custodian).publicbuiltin

Requires caller role >= admin. Creates a `user`/`guest` (a custodian caller may also create known custom roles) with optional db grants. Denies with `forbidden` on role gate or disallowed role.

Input

Field	Type
`username`	`string`	required
`password`	`string`	required
`role`	`string`	optional
`db_grants`	`string`	optional

Output

Field	Type
`success`	`bool`	required
`id`	`string`	required
`username`	`string`	required
`role`	`string`	required

Errors:bad_requestforbiddeninternal

auth.set_db_grantSet a user's per-db grant (role-gated: admin or custodian).publicbuiltin

Requires caller role >= admin. Upserts the user's `db:perm` entry (`perm` ∈ read|write|read_write|none) and re-serializes the grant CSV. Denies with `forbidden` on role gate.

Input

Field	Type
`username`	`string`	required
`db`	`string`	required
`perm`	`string`	required

Output

Field	Type
`success`	`bool`	required
`db_grants`	`string`	required

Errors:bad_requestforbiddeninternal

auth.promote_adminPromote a user to admin (role-gated: custodian only).publicbuiltin

Requires caller role >= custodian. Sets the target user's role to `admin`. Denies with `forbidden` on the role gate.

Input

Field	Type
`username`	`string`	required

Output

Field	Type
`success`	`bool`	required
`username`	`string`	required
`role`	`string`	required

Errors:bad_requestforbiddeninternal

auth.create_custodianCreate another custodian (role-gated: custodian only).publicbuiltin

Requires caller role >= custodian. Creates a new user with the `custodian` role. Denies with `forbidden` on the role gate.

Input

Field	Type
`username`	`string`	required
`password`	`string`	required

Output

Field	Type
`success`	`bool`	required
`id`	`string`	required
`username`	`string`	required
`role`	`string`	required

Errors:bad_requestforbiddeninternal

auth.define_roleDefine an RBAC role (role-gated: custodian only).publicbuiltin

Requires caller role >= custodian. Upserts a role definition `{name, perms}` in `_sys_roles`. Denies with `forbidden` on the role gate.

Input

Field	Type
`name`	`string`	required
`perms`	`string`	optional

Output

Field	Type
`success`	`bool`	required
`name`	`string`	required
`perms`	`string`	required

Errors:bad_requestforbiddeninternal

auth.require_role`before` gate: verify a signed bearer token + required role.publicbuiltin

Verifies an HMAC-signed `principal|roles|sig` bearer token and enforces the route's `required_role` (must be among the token's roles), injecting `{principal, roles}`. Denies with `forbidden`.

Input

Field	Type
`authorization`	`string`	required
`required_role`	`string`	optional

Output

Field	Type
`principal`	`string`	required
`roles`	`string`	required

Errors:bad_requestforbidden

kms#

kms.statusReport safe KMS status.publicbuiltin

Returns non-secret KMS state only: skeleton/storage version, locked/unlocked flag, unlock mode, AEAD provider, and honest not-wired markers for table encryption. It never returns seed material, DEKs, plaintext secrets, or ciphertext payloads.

Output

Field	Type
`kms`	`string`	required
`unlocked`	`bool`	required
`unlock_mode`	`string`	required
`encryption_at_rest`	`string`	required
`aead_algorithm`	`string`	required
`aead_available`	`bool`	required
`worker_secrets`	`string`	required
`catalogs`	`string`	required

Errors:bad_requestforbiddeninternal

kms.lockClear the process-local KMS root key.publicbuiltin

Locks the current process-local KMS state and returns the safe status shape. This does not erase encrypted catalog rows, but they cannot be opened until the process is unlocked again.

Output

Field	Type
`kms`	`string`	required
`unlocked`	`bool`	required
`unlock_mode`	`string`	required
`encryption_at_rest`	`string`	required
`aead_algorithm`	`string`	required
`aead_available`	`bool`	required
`worker_secrets`	`string`	required
`catalogs`	`string`	required

Errors:bad_requestforbiddeninternal

kms.unlock_ephemeralCustodian-only ephemeral KMS unlock for development/testing.publicbuiltin

Creates a process-local random root key. This is not the planned durable M-of-N custodian seed ceremony. It exists so encrypted secret catalog behavior can be developed and tested without claiming production KMS unlock is finished.

Input

Field	Type
`ctx.role`	`custodian`	required

Output

Field	Type
`unlocked`	`bool`	required
`unlock_mode`	`string`	required

Errors:bad_requestforbiddeninternal

kms.put_secretStore an encrypted app/worker-scoped secret.publicbuiltin

Admin+ function. Encrypts a UTF-8 secret value into `_sys_kms_secrets` using the current process-local root and AEAD AAD bound to app_id, worker_id, name, key_version, and algorithm. Does not expose plaintext in the stored row.

Input

Field	Type
`ctx.role`	`admin\|custodian`	required
`app_id`	`string`	required
`worker_id`	`string`	required
`name`	`string`	required
`value`	`string`	required

Output

Field	Type
`stored`	`bool`	required
`id`	`string`	required

Errors:bad_requestforbiddeninternal

kms.get_secretRead an app/worker-scoped secret server-side.publicbuiltin

Returns plaintext only to admin+ callers or to the matching worker id in the server-side request record. The value is for worker/server use and must never be placed into Quill island props or browser-visible state.

Input

Field	Type
`app_id`	`string`	required
`worker_id`	`string`	required
`name`	`string`	required

Output

Field	Type
`value`	`string`	required

Errors:bad_requestforbiddeninternal

kms.ceremony_beginBegin a custodian M-of-N master-seed ceremony (custodian-only).publicbuiltin

Generates a master seed in RAM, splits it M-of-N (Shamir), records a verifiable seed commitment, and creates N custodian slots. The seed is held only in a pending in-RAM slot and is never persisted in plaintext. Returns non-secret ceremony metadata; raw shares are wrapped via kms.ceremony_enroll, never returned to the browser. INTERIM: not yet behind governance voting (ADR-0006).

Input

Field	Type
`ctx.role`	`custodian`	required
`threshold`	`int`	required
`share_count`	`int`	required

Output

Field	Type
`ceremony_id`	`string`	required
`state`	`string`	required
`threshold`	`int`	required
`share_count`	`int`	required
`seed_commitment`	`string`	required

Errors:bad_requestforbiddeninternal

kms.ceremony_enrollWrap one custodian's share under their unlock key (custodian-only).publicbuiltin

Seals the next unassigned custodian share for the pending ceremony into a QiravaEnvelopeV1 bound to ceremony/custodian/purpose, using a caller-supplied 32-byte unlock key (hex). The unlock key models a passkey-PRF or seed-phrase derived key; it is used then dropped and never stored. Stores only the encrypted envelope and non-secret metadata.

Input

Field	Type
`ctx.role`	`custodian`	required
`ceremony_id`	`string`	required
`custodian_id`	`string`	required
`unlock_key_hex`	`string`	required
`purpose`	`string`	optional

Output

Field	Type
`custodian_id`	`string`	required
`share_index`	`int`	required
`enrolled`	`bool`	required

Errors:bad_requestforbiddeninternal

kms.ceremony_activateActivate a fully-enrolled ceremony (custodian-only).publicbuiltin

Requires all N custodians enrolled. Verifies the pending RAM seed against the recorded commitment, promotes the ceremony to active, and clears the pending RAM seed. Does not leave the KMS unlocked; operators unlock explicitly via kms.unlock_submit.

Input

Field	Type
`ctx.role`	`custodian`	required
`ceremony_id`	`string`	required

Output

Field	Type
`ceremony_id`	`string`	required
`state`	`string`	required
`threshold`	`int`	required
`share_count`	`int`	required

Errors:bad_requestforbiddeninternal

kms.unlock_beginReport what an unlock needs (no secret material).publicbuiltin

Returns the active ceremony id, threshold, and how many more distinct custodian submissions are needed to reconstruct the seed. Never returns seed/share material.

Output

Field	Type
`ceremony_id`	`string`	required
`threshold`	`int`	required
`needed`	`int`	required

Errors:bad_requestforbiddeninternal

kms.unlock_submitSubmit one custodian's unlock key toward M-of-N unlock (custodian/admin).publicbuiltin

Opens that custodian's stored envelope with the supplied 32-byte unlock key (hex) to recover one share into a RAM buffer. When >= M distinct valid shares are buffered, reconstructs and verifies against the commitment; on match the KMS root is set in RAM (the master seed is never returned). On mismatch it fails closed and audits. Fewer than M never unlock.

Input

Field	Type
`ctx.role`	`admin\|custodian`	required
`ceremony_id`	`string`	required
`custodian_id`	`string`	required
`unlock_key_hex`	`string`	required

Output

Field	Type
`accepted`	`int`	required
`needed`	`int`	required
`unlocked`	`bool`	required

Errors:bad_requestforbiddeninternal

Apps

Studio — the system app

Qirava Studio is the built-in admin app: schema and data browsing, user and grant management, and API-key minting. It is an ordinary DMS client with no backdoor — every action it takes goes through the same execute → worker → planner path and the same three authorization checkpoints as any caller.

Planned

Cloud — managed Qirava

Managed Qirava Cloud is planned: the same open-core engine and API, run for you with single-leader replication, custodian-gated onboarding, and hardware-attested key custody. The wire API is identical to self-hosted — the catalog on this page is the contract either way.