HTTP API

The Rad wire protocol: a small JSON over HTTP surface that clients and a Rad server speak to each other.

Errors use RFC 7807 Problem Details. Branch on the stable code field rather than parsing an error message.

Endpoints

Meta

Liveness and schema introspection.

GET /healthz

A cheap check that touches no storage. It always returns 200 with a small status body while the process is serving, so it is safe to use as a rad:// reachability test before opening a connection. It is database metadata, not an orchestrator signal: use /readyz and /livez for those.

Responses

GET /info

Return stable metadata for the database behind this endpoint. mode tells management tools whether catalog changes are available directly through the API or are owned by rad.schema.yaml migrations. schema_version identifies the latest committed catalog state, and schema_version_at reports when that version committed. location is the server's configured storage location and is intended for local development and administrative tooling.

Responses

GET /statistics

Return the distilled model repository the planner estimates from: one entry per relation family, with observed row counts, estimate quality, execution latency, and the physical plans seen for it.

These are query-planner statistics, not operational metrics or tracing. They are advisory: deleting them changes no query result, and they are gathered best-effort, so a value may be missing after process failure or backpressure.

Several fields are deliberately approximate and named accordingly. A field ending UpperBound is a histogram bucket bound rather than an exact quantile, so it overstates; the matching exact maximum is reported beside it. Read the field descriptions before comparing numbers.

A process that runs no collector; a reader instance gathers statistics only for its own planner and a writer is the only publisher; returns 404 rather than an empty body, so "this instance does not collect" is distinguishable from "nothing observed yet".

Responses

GET /tables

Return every table currently defined in the catalog, along with its columns and primary key. This reflects the schema as it exists right now, after the most recent successful migration. An empty database returns an empty list, not an error.

Use this to introspect a running server without access to the original rad.schema.yaml file.

Responses

Probes

Process probes for orchestrators such as Kubernetes. They describe the serving process rather than the database's contents, never mutate catalog or application data, and are answerable before the database itself is available. An orchestrator decides from the HTTP status alone.

GET /livez

Succeed while the process serves requests and every critical background task is alive. Storage never fails this probe: a temporary object-store or network outage must withdraw traffic through /readyz rather than restart a process that would come back to the same outage.

The reason is live, draining, or task_failed.

Responses

GET /readyz

Succeed only while the process can serve the read or write access it was started with. It fails as soon as shutdown begins, as soon as the writer is fenced, and while storage is failing or has not been observed within the freshness window. A background task refreshes that observation, so answering the probe never issues a new object-store request.

The reason is starting, serving, draining, fenced, storage_unavailable, or storage_stale.

Responses

GET /startupz

Succeed once storage is open, the catalog's identity and mode are validated, and the required background workers are running. Until then the process answers the probe endpoints and nothing else, so an orchestrator can bound initial storage startup without restarting a process that is still opening a slow object store, and no client reaches a partially initialized database.

A storage preflight monitors the object store while startup is held. The preflight sets the reason to show the cause of the hold. On success, the reason is started. While startup is held, the reason is starting, storage_bucket_missing, storage_unauthorized, or storage_unreachable.

Responses

Schema

Reconciling the database with a rad.schema.yaml file.

POST /schema/compatibility

Verify an exact generated-client schema identity.

Request body

Responses

POST /schema/diff

This is an advisory point-in-time plan. The planner may account for matching durable work already in progress and omit a duplicate transition-start statement. Apply replans against current state and returns the authoritative transition identities accepted for the migration; diff does not return durable transition handles.

Request body

Responses

POST /schema/migrate

The server parses the desired schema, computes and preflights its semantic diff, and atomically commits immediate catalog work plus any durable online transition starts. The response is ready only when the current canonical schema equals desired_hash; otherwise it is converging and returns the transition identities to observe through the administrative API. Repeating the same desired-schema request recovers matching in-flight transitions instead of duplicating them. Destructive findings require accept_data_loss; blocking findings can never be bypassed.

Request body

Responses

GET /schema

Return the committed canonical schema together with its monotonic version and canonical hash.

Responses

Administration

Inspecting and controlling durable database maintenance work.

POST /schema/transitions/{transition}/cancel

Atomically invalidate worker ownership, remove the transition's foreground write obligations, and schedule partial physical state for reclamation. Cancellation is idempotent for an already-cancelled transition. Ready and failed transitions reject cancellation because they require deletion or cleanup instead. This administrative transaction cannot be interleaved with application statements in a PIR program and is available in both catalog management modes.

Parameters

Responses

GET /schema/transitions/{transition}

Return the current durable identity and lifecycle state plus advisory progress and retained-work pressure. The observation is read from one coherent storage snapshot and does not claim or advance a worker.

Parameters

Responses

GET /schema/transitions

Return a coherent administrative snapshot of online schema work, including terminal transitions retained for diagnostics. Optional kind and state filters are applied to that snapshot. This endpoint never claims a worker or advances transition progress and is available in both direct and schema-managed catalog modes.

Parameters

Responses

Catalog

Imperative catalog mutation: creating, updating, and deleting tables, columns, and indexes over the API. Available only on directly managed databases; a schema-managed database rejects every operation in this group with an invalid problem, since its catalog is owned by rad.schema.yaml migrations.

DELETE /tables/{table}/columns/{column}

Remove a column. Stored values for it become unreachable. A column used by the primary key, an index, or a foreign key cannot be deleted; delete the index or foreign key holder first. On a schema-managed database this operation is always rejected.

Parameters

Responses

PATCH /tables/{table}/columns/{column}

Update a column's properties. The only updatable property today is name; changing a column's type or nullability is not supported. A name change rewrites every metadata reference to the column (primary key, indexes, foreign keys), and rows are keyed by column ID, so no data is touched. On a schema-managed database this operation is always rejected.

Parameters

Request body

Responses

POST /tables/{table}/columns

Append a column. Because existing rows have no value for it, the column must be nullable or carry a literal default. A nullable column may use a generator default; historical rows remain NULL while new creates run the generator. On a schema-managed database this operation is always rejected.

Parameters

Request body

Responses

DELETE /tables/{table}/indexes/{index}

Remove an index from the catalog. Its entries become unreachable; index IDs are never reused. Queries that would have used it fall back to other access paths. On a schema-managed database this operation is always rejected.

Parameters

Responses

POST /tables/{table}/indexes

Register a secondary index and backfill entries for every existing row, atomically: the index never becomes visible without its entries. Backfilling a unique index over data that already contains duplicates fails with an invalid problem; retrying cannot succeed until the data changes; and the registration is rolled back with it. On a schema-managed database this operation is always rejected.

Parameters

Request body

Responses

DELETE /tables/{table}

Remove a table from the catalog. Its rows and index entries become unreachable; table IDs are never reused. A table that another table references through a foreign key cannot be deleted until the referencing table goes first (self-references do not count). On a schema-managed database this operation is always rejected.

Parameters

Responses

PATCH /tables/{table}

Update a table's properties. The only updatable property today is name: data keys use the table's ID, so a name change is metadata-only and instantaneous, and foreign keys referencing the table are unaffected. A name that is already taken is rejected with an invalid problem. On a schema-managed database this operation is always rejected.

Parameters

Request body

Responses

POST /tables

Define a new table in one call: columns, primary key, and optionally indexes and foreign keys, exactly as a rad.schema.yaml entry would. Stable schema IDs may be supplied or are assigned by the catalog, and the whole definition commits atomically; a rejected definition leaves nothing behind, including the name.

Foreign keys may reference existing tables or the table being created (self-references), and must target the referenced table's full primary key. A definition that fails validation; duplicate or missing name, unsupported column type, nullable primary key column, index or key over unknown columns; is rejected with an invalid problem. On a schema-managed database this operation is always rejected.

Request body

Responses

Data

Reading and writing rows against committed state.

OPTIONS /execute

Describe the operations available at the execute target.

Responses

POST /execute

Execute a program: an ordered list of named statements run as one atomic transaction. Each statement is a query, create, update, or delete over an LIR relation, and evaluates against the transaction's snapshot plus the effects of all preceding statements. A statement's result is available to later statements, by name, through an LIR ref; statement names share the binding namespace.

Mutations consume relations rather than literal rows: create inserts a relation's rows, update and delete identify target rows by the relation's primary-key columns. A literal row is simply a one-row rows relation.

Exactly one statement's result is returned, named by result (or the sole statement of a single-statement program). The response also carries a per-statement summary of affected row counts. If any statement fails validation or execution, or the commit loses a serializable race, the whole program fails and no effects become visible; a failed statement is named in the error.

The program envelope is validated before binding, and each statement's LIR relation against the independent LIR schema. Binding then resolves tables, columns, scopes, and statement references (which must point at earlier statements).

Parameters

Request body

Responses

QUERY /execute

Execute one LIR query against one committed snapshot. This operation cannot contain PIR statements or mutations. A successful response has a weak entity tag for the exact query and its complete dependency state. A matching If-None-Match returns 304 without executing the relation or serializing its result.

Parameters

Request body

Responses

Data shapes

These reusable objects appear in request bodies, responses, and error details.

Access

Whether this process serves a checkpoint reader or owns the Slate writer.

ColumnDef

A column definition for a direct catalog create operation.

ColumnDefault

A column default, applied when an insert omits the column: either a builtin generator named by func (uuid_v4 or uuid_v7 on bytes format: uuid, ulid on bytes format: ulid, xid on bytes format: xid, and now_ms or increment on int64 columns) or a literal value of the column's type. Exactly one is set.

ColumnInfo

One column of a table, as reported by introspection.

ColumnUpdateProps

The column properties to update.

ConflictContext

Schema-level identity for a raced object, when resolvable.

ConflictObject

ConflictOperation

ConflictProblem

DatabaseInfo

Stable metadata about a Rad database.

ExecutionContext

The physical execution identity available at failure.

ExecutionFailedProblem

ForeignKeyAction

The action applied to referencing rows when the referenced row is deleted.

ForeignKeyInfo

One foreign key, in both definitions and introspection. The referenced columns must be the referenced table's full primary key.

Health

The liveness status of the server.

IndexInfo

One secondary index, in both definitions and introspection.

InternalProblem

A database failure that prevents the operation from completing. The detail contains the complete available diagnostic, including wrapped causes. incident correlates the response with the server log.

InvalidDiagnostic

One diagnostic within a multi-error invalid problem.

InvalidProblem

NotFoundProblem

ProbeStatus

Why a probe answered as it did. The HTTP status is the answer; this body is a diagnostic for whoever is reading curl output or a failing test, and orchestrators ignore it.

Problem

An RFC 7807 Problem Details object. Every non-2xx response carries one. code is the stable top-level discriminator; reason is the fine-grained semantic identity within that class.

Variants: InvalidProblem, ExecutionFailedProblem, NotFoundProblem, ConflictProblem, InternalProblem

ProblemBase

ProblemLocation

Identifies the request construct associated with the problem. JSON Pointer is machine-navigable; the other fields are semantic labels. Fields are omitted when that provenance is unavailable. Table, index, column, binding, and node names may appear; key bytes and row values never do.

ProblemStage

The engine stage that rejected or failed the operation.

Program

An arbitrary JSON object containing a PIR execution program. As with Query, the HTTP contract does not describe the PIR grammar; servers validate this raw body against the independent PIR JSON Schema, and each statement's relation against the LIR schema.

ProgramResult

The result of a program: the declared result statement's datum (shaped exactly as its LIR root materialises, as in QueryResult), plus a per-statement summary in execution order.

Query

An arbitrary JSON object containing one LIR query. The HTTP contract does not duplicate the LIR grammar. Servers validate this body against the independent LIR JSON Schema.

QueryResult

The result of a query: one datum, shaped exactly as the root materialises. A many root is an array of records; first is a record or null; exactly_one is a record; scalar is a naked value or null. Nested first fields are objects (or null) and nested array fields are arrays, recursively.

ResourceContext

The addressed API resource, without storage keys or row values.

SchemaChange

SchemaCompatibilityRequest

SchemaDiffResult

An advisory point-in-time comparison with the desired schema. program is the work a newly accepted apply would currently need; it may omit a transition start when matching durable work is already in progress. Apply replans transactionally and returns its authoritative transition identities.

SchemaDocument

The accepted canonical logical schema.

SchemaFinding

SchemaMigrateRequest

A desired schema, the preflighted server identity, and explicit data-loss consent.

SchemaMigrateResult

SchemaRequest

A desired schema source to plan.

SchemaState

StatementResult

One statement's lightweight outcome. Durable schema work additionally returns a typed control object; relational and immediate catalog statements omit it.

Statistics

StatisticsColumnGroupSynopsis

StatisticsColumnSynopsis

StatisticsCorpus

StatisticsCorpusMaintenance

Cumulative maintenance counters and current retained corpus gauges. Counters start when the storage owner process starts.

StatisticsModel

StatisticsMostCommonColumnGroup

StatisticsMostCommonValue

StatisticsPhysicalCacheCost

StatisticsPhysicalCost

Instance-local physical storage calibration. Backend adapters convert their native metrics to this common model. A missing capability is false and its measurements are absent. The model is not assigned to one statement or relation.

StatisticsPhysicalCostMetric

StatisticsPhysicalRequestCost

StatisticsPhysicalTelemetryCapabilities

StatisticsPlan

StatisticsPlanningValue

Observational priority proxy. It is present only when at least two plans have enough execution evidence in the same access generation and row-count class. It does not claim that an estimate caused a plan change. A future counterfactual optimizer can replace the observed A counterfactual optimizer replaces the observed plan-variation component without changing the other components.

StatisticsRelay

The observation relay, as this instance sees it. An instance that cannot publish to storage hands its evidence to one that can; the channel is advisory, so every loss here is counted rather than signalled as a failure.

The sending fields are absent on an instance that publishes to storage rather than to a peer. The receiving fields are always present, because every instance can receive; zero means nothing has arrived.

StatisticsResourceCost

Observed logical KV work for complete statement executions. This is not CPU, memory, object-request, or remote-I/O cost. A relation model has no resource cost because shared statement work cannot be assigned to one relation without an operator measurement boundary.

StatisticsResourceMetric

StatisticsSynopsis

TableDef

A new table's definition, mirroring a rad.schema.yaml entry as JSON. The direct API may omit logical IDs for the catalog to allocate. Column types are text, int64, float64, bool, or bytes; the primary key is required and its columns must not be nullable.

TableInfo

One table's definition, as reported by introspection.

TableList

The set of tables defined in the database.

TableUpdateProps

The table properties to update.

TransitionControl

The administrative projection of a durable schema transition. Identity, protocol kind, lifecycle state, generation, prerequisite edges, and terminal diagnostics are normative. Progress and retained-work values are advisory snapshots. Worker epochs and physical storage positions remain internal.

TransitionKind

The physical protocol used to perform online schema work.

TransitionList

A coherent administrative snapshot of durable schema transitions.

TransitionState

The durable lifecycle state of online schema work.

TransitionWorkState

Advisory retained-work pressure. write_gated means affected writes are temporarily rejected until the worker catches up or terminates.

Value

An arbitrary JSON value carried by the HTTP protocol.