GET /agdx/capabilities reply: what the /agdx/* surface offers on this
server, so a browser client can feature-detect before showing the
projections / query / KV / fork views. Richer than the binary AGDX_HELLO
probe (per-surface flags plus the wire op versions the JSON bodies must
match), and it answers truthfully even when the managed backend is disabled (200
with managed: false).
One connection on the GET /agdx/clients discovery surface. metadata is
URL-safe unpadded base64 of the opaque advertised bytes (a JSON string cannot
carry raw bytes), or None when the connection advertised none. The console
decodes and interprets it per producer kind (an agent card or an app blob).
GET /agdx/clients query parameters: the discovery filters and the page
window, all optional. Shared by the server handler and the typed client so the
query string cannot drift between them.
The canonical error body every /agdx/* route returns on a non-2xx status.
The HTTP binding’s rule is “a 2xx carries the bare Ok payload, a failure
carries this”: the status line gives the coarse class (from
ResultCode::http_status) and this body gives the machine-dispatchable
ResultCode plus a human message, so a client matches on code instead
of grepping the message text (which is for humans and may change). detail
carries optional structured context (e.g. the conflicting version on a CAS
miss) as free-form JSON.
Consumer filters on the HTTP capabilities reply. Native evaluation is served
by the streaming server itself and holds with the managed backend off. The
catalog (saved filters and group bindings) needs the backend.
GET /agdx/graph/{name}/neighbors/{node} query: the traversal direction
(out, in, or both, omitted for the default out), an optional edge-type
filter, the hop depth (omitted for the default one hop), and a result limit
(omitted for the backend ceiling). One struct shared by the typed client and
the server route, so the two cannot drift.
One graph node on the HTTP surface: id as a string, its labels, and its
attributes rendered as strings (e.g. the entity value) for a browser or
wasm client that has no access to the typed Value.
PUT /agdx/kv/{namespace}/{key}/cas query: the compare-and-swap precondition
plus an optional expiry. Exactly one of expect_version (match the held
version) or expect_absent (create-if-absent) is set, mirroring the binary
CasExpect. The value rides the raw request body.
One KV entry on the HTTP surface. key and value are URL-safe unpadded
base64, because keys and values are arbitrary bytes that JSON strings
cannot carry raw.
GET /agdx/projections filters. Every field is optional, and an absent field is
omitted from the query string (no empty topic=). Field names are the
PARAM_* consts verbatim, so the client serializer and the server parser
share one spelling.
POST /agdx/schemas body: the register request without an id. The managed
backend allocates it and the reply carries it back as
{"SchemaRegistered":id}.
DELETE /agdx/bindings body: which binding to remove, by its source stream
and topic. projection_ref absent removes the whole binding for that source.
projection_ref present removes only that one projection from the binding,
leaving the rest. Mirrors ControlCommand::RemoveBinding.
GET /agdx/schemas filters. name_contains is the substring filter on a
schema’s optional name, the same spelling as the projection list, so the two
list surfaces share one filter vocabulary.
?stream= on GET/DELETE /agdx/schemas/{id} and
POST /agdx/schemas/{id}/decode: the stream whose registry holds the id.
Absent addresses the deployment-wide registry.
GET /agdx/clients to list live connections with their advertised metadata,
filtered and paginated by query parameters. The HTTP face of the
AGDX_GET_CLIENTS_METADATA discovery read.
Response header on GET /agdx/kv/{namespace}/{key} carrying the entry’s
absolute expiry (epoch microseconds) as a decimal string. The value itself
rides the raw response body, so this header carries the one piece of
out-of-band metadata a single-key read needs. Owned here so the name is a
wire constant rather than an unscoped string. Absent means no expiry.
?search= on GET /agdx/projections: one substring matched against the
projection name OR id. A console with a single filter box maps to it. A
server matches it as name_contains(name) OR id contains search. Composes
(AND) with the narrower name_contains / id_prefix when several are set.
DELETE/GET /agdx/graphs/{id}: drop or read a graph projection. The id
is percent-encoded as one path segment, like every name below, because a
stream-scoped name holds /.
PUT /agdx/kv/{namespace}/{key}/cas: a conditional write (compare-and-swap).
The precondition rides the query string (expect_version or expect_absent)
and the value rides the raw body, like the plain PUT. A success replies
CasCommittedView with the new version, a precondition miss replies 409
with an ErrorBody of code conflict whose detail carries the current
version.
GET/PUT/DELETE /agdx/kv/{namespace}/{key}. key is the URL-safe
unpadded base64 form of the key bytes, the encoding this surface uses for
every binary body.