Queries — io.best.agents.queries

Queries are synchronous reads of current state — the read-before-write complement to commands (e.g. an agent lists broker accounts before referencing one in a command). Declared in the manifest like any other capability. Schema: queries.json

Method	Path	Description
GET	/queries	Query catalogue — same entry shape as the command catalogue (schema, version, dataschema, description, optional workflows)
GET	/queries/{schema}/{version}	Query schema document
GET	/queries/{schema}	Execute — parameters as query string; returns 200 with the result body

The schema document has up to three sections: description, parameters (JSON Schema for accepted query-string parameters — omitted when the query takes none), and response (JSON Schema for the result body; required) — plus the optional workflows cross-link array when the service publishes workflows.

The parameters schema governs what an execution accepts: the query string is validated against it, each value a string, so the schema declares its parameters as strings (a number by a pattern), and a failure is a 400 whose details name the parameter. A parameter the schema does not declare is refused only when it says additionalProperties: false; a query whose document has no parameters ignores any it is sent.

GET /queries                    → discover available queries
GET /queries/list-brokers/1.0   → learn parameters and response shape
GET /queries/list-brokers       → execute; 200 + JSON body
POST /commands                  → now you have the ID you needed

Execution returns 400 for missing/invalid parameters, 404 for an unknown schema name.

Queries are not a query language (no filter expressions, joins, or aggregations), not a REST resource hierarchy (no per-item GETs), and not event sourcing (they return current state as the service projects it — historical facts live in GET /events).

Queries beside the other capabilities

Unlike commands (queued, results observed afterwards), a query returns its result directly in the HTTP response body and changes nothing.

Capability	HTTP	Returns	Changes state?
agents.commands	POST /commands	201 (async)	Yes
agents.events	GET /events	Event history	No
agents.queries	GET /queries/{schema}	Current state (sync)	No

BEST queries are a single, fixed GET pattern with catalogue-driven discovery, and do not replace OpenAPI: a service's own API can have both.