HTTP query API
Read-only endpoints exposed by idiolect-orchestrator under the
query-http feature. All requests are GET. All responses are
JSON.
The route surface is generated from
orchestrator-spec/queries.json. Each query maps onto two
endpoints: a friendly REST path under /v1/… and an
ATProto-style xrpc path under
/xrpc/dev.idiolect.query.<queryName>. Both call the same
handler. The snapshot below reflects the spec at v0.8.0.
Liveness and metrics
| Path | Returns |
|---|---|
GET /healthz | 200 OK if the process is alive. |
GET /readyz | 200 OK once the catalog has caught up. |
GET /metrics | Prometheus exposition. |
GET /v1/stats | Per-kind record counts. |
Generated query endpoints
| REST path | xrpc path | Returns |
|---|---|---|
GET /v1/bounties/open | /xrpc/dev.idiolect.query.openBounties | Bounties whose status is open, claimed, or unset. |
GET /v1/bounties/want-lens?... | /xrpc/dev.idiolect.query.bountiesForWantLens | Bounties whose wants is a specific lens. |
GET /v1/bounties/by-requester?requester_did=... | /xrpc/dev.idiolect.query.bountiesByRequester | Bounties by requester DID. |
GET /v1/adapters?framework=... | /xrpc/dev.idiolect.query.adaptersForFramework | Adapters declared for a framework. |
GET /v1/adapters/by-invocation-protocol?... | /xrpc/dev.idiolect.query.adaptersByInvocationProtocol | Adapters by invocation-protocol kind. |
GET /v1/adapters/with-verification?... | /xrpc/dev.idiolect.query.adaptersWithVerification | Adapters that carry at least one verification record. |
GET /v1/recommendations | /xrpc/dev.idiolect.query.recommendationsStartingFrom | Recommendations starting from a given source schema. |
GET /v1/verifications?lens_uri=... | /xrpc/dev.idiolect.query.verificationsForLens | Verifications for a specific lens. |
GET /v1/verifications/by-kind?... | /xrpc/dev.idiolect.query.verificationsByKind | Verifications by kind. |
GET /v1/communities?... | /xrpc/dev.idiolect.query.communitiesForMember | Communities for a member DID. |
GET /v1/communities/by-name?... | /xrpc/dev.idiolect.query.communitiesByName | Communities by name. |
GET /v1/dialects/for-community?... | /xrpc/dev.idiolect.query.dialectsForCommunity | Dialects owned by a community. |
GET /v1/beliefs/about?... | /xrpc/dev.idiolect.query.beliefsAboutRecord | Beliefs whose subject is a given record. |
GET /v1/beliefs/by-holder?... | /xrpc/dev.idiolect.query.beliefsByHolder | Beliefs by holder DID. |
GET /v1/vocabularies/by-world?... | /xrpc/dev.idiolect.query.vocabulariesWithWorld | Vocabularies declared with a given world. |
GET /v1/vocabularies/by-name?... | /xrpc/dev.idiolect.query.vocabulariesByName | Vocabularies by name. |
The authoritative parameter list per endpoint is in
orchestrator-spec/queries.json.
The codegen-emitted handlers live in
crates/idiolect-orchestrator/src/generated/http.rs.
Response shape
List endpoints return a JSON envelope whose exact shape is
generated per query. The general pattern: a top-level object
carrying the result list plus pagination metadata. See the
emitted Rust types in
crates/idiolect-orchestrator/src/generated/ for the precise
shape per endpoint.
Error shape
A request that fails parameter validation returns 400 with a JSON body identifying the offending field. Internal failures return 500 with a brief message.
Versioning
The v1 and /xrpc/ prefixes are the route contract. New
endpoints are additive. Pre-1.0 the project may rename or
restructure endpoints between minor versions. See
Stability and versioning. At 1.0 the prefixes
become stable and breaking changes ship under v2 (or, for the
xrpc surface, under new method names that deprecate the old).