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 /health

A cheap liveness probe 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 readiness check or a rad:// reachability test before opening a connection.

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 /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

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; generator defaults (uuid(), now_ms()) are rejected on new columns of existing tables since they would produce a different value on every read of an old row. 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.

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

Data shapes

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

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 on text columns, now_ms on int64 columns) or a literal value of the column's type. Exactly one of the two 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

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 deliberately impoverished internal failure. Wrapped causes, locations, execution context, catalog identity, keys, and values are never exposed. incident is an optional opaque log correlation ID.

InvalidDiagnostic

One diagnostic within a multi-error invalid problem.

InvalidProblem

NotFoundProblem

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.

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.

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, or bool; 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.