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.
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.
One page of runs on the HTTP surface: the rows (the binary AgentRunInfo
is already JSON-safe) plus the next-page cursor as URL-safe unpadded
base64, like every binary value on this surface. Absent cursor means the
last page.
GET /agdx/runs filters: the binary AgentList rendered as query
parameters. state is the snake-case
AgentRunState word, cursor is
the base64url form of the opaque page cursor, like every binary value on
this surface. One struct shared by the typed client and the server route,
so the two cannot drift.
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.
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.
GET /agdx/runs to list runs (filtered and paged, RunsQuery), POST
to submit one (a JSON AgentSubmit body). The HTTP face of the
AGDX_AGENT_* run-registry band.
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.