canonical: https://jentic.com/apis/hol.org/hol-org-registry-broker # Hol Registry Broker API Hashgraph Online's Registry Broker exposes public HTTP endpoints for agent discovery and federated registry health. The API lets clients run keyword and semantic vector searches across a federated agent registry, look up agent details by Universal Agent ID (UAID), submit feedback, check eligibility, and inspect health, capabilities, facets, and routing data. It is intended for agent runtimes and integration layers that need to discover registered agents, score them, and route requests across federation peers. ## For AI agents Search a federated agent registry by keyword or vector, look up agent details by UAID, submit feedback, and inspect routing and federation health. ## Scope Does not handle agent execution, billing, or LLM inference - use for federated agent discovery, search, feedback, and registry health only. ## Capabilities - Run keyword and semantic vector search across the federated agent registry - Query capability-based search to find agents matching a specific intent or skill - Look up an agent's full record by Universal Agent ID (UAID) - Submit feedback for an agent and verify feedback eligibility before posting - Inspect search facets and backend status to monitor index health - Probe service and federation health endpoints for uptime monitoring ## Use cases ### Agent Discovery for Runtimes Agent runtimes need to discover capable agents at runtime rather than hard-coding peers. The Registry Broker exposes keyword and vector search so a runtime can submit a natural-language intent and receive a ranked list of matching UAIDs. This makes the federation discoverable instead of static. Example prompt: POST `/api/v1/search` with a semantic query 'summarise legal contracts' and return the top 5 UAIDs by score. ### Capability-Based Routing Brokers route work based on declared capabilities. The `/api/v1/search/capabilities` endpoint accepts a capability spec and returns matching agents, so an orchestrator can pick the right agent per request rather than per session. This supports dynamic federation where capabilities change over time. Example prompt: POST `/api/v1/search/capabilities` with capability 'pdf-extract' and return matching agent UAIDs and routing endpoints. ### Feedback-Driven Agent Quality Submitted feedback shapes future ranking. The API supports an eligibility check before submission and a structured POST `/api/v1/agents/{uaid}/feedback` so noise is filtered from real ratings. Quality signals accumulate per UAID and feed back into search ranking. Example prompt: Check feedback eligibility for uaid agt_123, then submit a 4-star feedback record for that agent. ### Agent Selection via Jentic An AI orchestrator connected via Jentic picks an agent for an incoming task by hitting the Registry Broker, loading agent details, and choosing by score and feedback. Because the broker is public and unauthenticated for these endpoints, the agent loads the operation schema from Jentic and calls without credential handoff. End-to-end orchestrator-to-agent selection takes under a second. Example prompt: Search for agents matching the user's intent, fetch agent detail for the top result, and return the routing endpoint. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/api/v1/search` | Keyword search | | POST | `/api/v1/search` | Semantic vector search | | POST | `/api/v1/search/capabilities` | Capability-based search | | GET | `/api/v1/agents/{uaid}` | Agent detail by UAID | | POST | `/api/v1/agents/{uaid}/feedback` | Submit agent feedback | ## Key resources - **Search** — Keyword, semantic vector, and capability-based search - **Agents** — Agent records by UAID with detail, feedback, and eligibility - **Health** — Liveness and readiness probes - **Registries** — Per-registry scoped search and metadata - **Federation** — Federation peer and routing inspection ## Why Jentic - **Setup:** Wiring the Registry Broker API by hand still means routing each call to the right federated discovery, search, or feedback endpoint and resolving its base host, even though the public endpoints need no credentials. Through Jentic you install once, import the Registry Broker API from the API Directory, and your agent calls it through the same execution path as keyed APIs. - **Permission scoping:** The public Registry Broker endpoints are unauthenticated and centered on discovery and search rather than scopable owned resources, so scoping stays at the operation level: limit the agent to the operations it needs, such as searching for agents or reading an agent by uaid. You choose that set, so submitting feedback is only available if you include it. - **Credential handling:** The public Registry Broker endpoints need no credentials, so there is nothing to store, and if you deploy the broker behind a private gateway its credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'find an agent that can summarise documents', and Jentic returns the matching Registry Broker operation with its input schema so the agent calls the right discovery endpoint without reading the broker docs. ## Related APIs - **OpenAI API** — LLM API used to interpret search intent before calling the Registry Broker - **Anthropic Messages API** — LLM API for orchestrators that select and call agents from the Registry Broker - **Render API** — Hosting platform that runs registry brokers and federation peers ## FAQ ### What authentication does the Registry Broker API use? The Registry Broker exposes its public discovery endpoints without authentication; no security scheme is declared on these operations. Through Jentic, agents call the public surface directly without holding credentials. Restricted operations require the deploying registry to wire its own auth on top. ### Can I run semantic vector search through the Registry Broker? Yes. POST `/api/v1/search` accepts a semantic vector search payload that returns ranked UAIDs by similarity. GET `/api/v1/search` runs keyword search for simpler lookups. Use POST `/api/v1/search/capabilities` when matching against declared capability tags rather than free text. ### What are the rate limits for the Registry Broker API? The Registry Broker spec does not declare hard rate limits. Treat the public endpoints as moderate-volume; back off on 429 responses. For heavy orchestrator workloads, coordinate with the registry operator on expected traffic. ### How do I look up an agent by UAID through Jentic? Search Jentic for 'lookup agent by uaid', load GET `/api/v1/agents/{uaid}`, and execute with the UAID. Run pip install jentic and use the async SearchRequest, LoadRequest, ExecutionRequest pattern to retrieve the agent record. ### Does the Registry Broker support feedback submission? Yes. Use POST `/api/v1/agents/{uaid}/feedback/eligibility` to check whether the caller can submit feedback, then POST `/api/v1/agents/{uaid}/feedback` with the rating and comment payload. Eligibility checks help filter spam from genuine ratings. ### Can I limit what my agent is allowed to do with the Registry Broker API? Yes. Because you run Jentic One yourself, your own rules decide which Registry Broker operations the agent may call, and the endpoints are unauthenticated discovery and search calls rather than owned resources, so scoping happens at the operation level. You can grant only the operations the agent needs, such as keyword and semantic search on `/api/v1/search` or reading an agent record with GET `/api/v1/agents/{uaid}`, and withhold the rest. Writing operations like POST `/api/v1/agents/{uaid}/feedback` are available only if you choose to include them in the set. This keeps the agent limited to discovery and lookup unless you explicitly allow it to submit feedback.