> For the complete documentation index, see [llms.txt](https://docs.nfh.global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nfh.global/product-documentation/products/discovr.md).
# DISCOVR — find catalogs
Welcome to the documentation for NFH fabric DISCOVR — the Discovery Service (DS) of the NFH fabric ecosystem.
> **Realises the NFH fabric** [**Discovery Edge**](/product-documentation/products/discovr.md) **service.**
Welcome to the documentation for NFH fabric DISCOVR — the Discovery Service (DS) of the NFH fabric ecosystem. It is a high-performance, real-time discovery engine that enables consumers to find resources across all published catalogues in NFH fabric-enabled networks.
This guide is intended for Consumer Node (CN) developers, consumer application builders, network facilitators, and anyone building search experiences on top of NFH fabric catalogues.
High-level catalog data flow
### What is NFH fabric DISCOVR?
NFH fabric DISCOVR is the query-time search and discovery layer for NFH fabric ecosystems. It runs on the consumer node side of the network — it exists to serve consumer applications' search requests, not to publish or manage provider catalogues.
A Provider Node self-hosts and self-signs its own catalogue on infrastructure it controls (see [Catalog Publishing and Discovery](/build/creating-a-network/catalog-publishing-and-discovery.md)); DISCOVR (DS) is purpose-built for **real-time search** — it crawls, independently verifies, and indexes catalogue data straight from every provider's own storage, and exposes it through fast, flexible query APIs that power consumer-facing search experiences.
DISCOVR runs its own crawler: it resolves each provider's Registry record, fetches and verifies that provider's signed catalogue index and files directly, indexes what it has verified, and serves discovery requests from Consumer Nodes (CNs) and consumer applications with sub-second response times. A provider's catalogue starts flowing into DISCOVR as soon as its Registry record points at a crawlable index — see [How DISCOVR Stays Updated](#how-discovr-stays-updated) below.
### Why Do You Need NFH fabric DISCOVR?
Without a dedicated discovery layer, consumer applications face:
* Querying raw catalogue data directly — slow, unstructured, and unscalable
* Building custom search indexes per application — duplicated effort, inconsistent results
* No support for natural language, spatial, or attribute-based search across providers
* No unified view of resources across multiple catalogues and networks
NFH fabric DISCOVR solves this by offering:
* **One search endpoint** across all catalogues published to the network
* **Multiple search modes** — natural language, keyword, spatial (location-based), and JSONPath attribute filtering
* **Real-time indexing** — catalogue changes a provider publishes are indexed and searchable within seconds
* **Provider-agnostic results** — consumers see resources from all providers, with offers from multiple retailers in one response
### Key Capabilities
#### For Consumer Nodes (CNs)
* **Natural language search** — ask questions like "strong Assam tea for morning chai" or "premium coffee under 500 rupees"
* **Keyword search** — find resources by name, description, brand, or any indexed attribute
* **Spatial search** — find resources available near a location using GeoJSON coordinates and distance radius
* **Attribute filtering** — query resources and offers using JSONPath expressions for fine-grained filtering (e.g., "flat discount offers under ₹100")
* **Combined queries** — mix text search with spatial constraints in a single request
* **Schema-aware results** — responses include full resource attributes, ratings, offers, and provider details
#### For Discovery Service (DS) Builders
* **Crawler-fed indexing** — DISCOVR runs its own crawler against every provider's self-hosted, self-signed catalogue index — no push, no subscription, no central relay in the path
* **Full-text and spatial search** — supports keyword matching, natural language understanding, and geospatial proximity queries
* **Quality-assured results** — every catalogue is signature- and digest-verified before indexing, then deduplicated and pruned before being served to consumers
#### For Network Facilitators
* **Network-wide search** — query across all providers and catalogues in a network
* **Schema type filtering** — discover resources by domain type (e.g., GroceryItem, ChargingService, HealthcareProvider)
* **Offer comparison** — see multiple retailer offers for the same resource in one response
* **Real-time availability** — search results reflect the latest published catalogue state
### High-Level Architecture
```
Provider Node DISCOVR
(self-hosted, self-signed catalogue) (crawler + search engine)
| |
| Registry record: catalog_index_urls |
|<-------------------------------------------- resolve
| |
| GET catalogue index + files |
|<-------------------------------------------- crawl, on its own schedule
| signed index + catalogue files |
|--------------------------------------------> verify signatures + digests
| | Index for search
| | Store for spatial queries
| |
| |
Consumer Node (CN) |
| |
| POST /discover |
| (text / spatial / JSONPath) |
|------------------------------------------->|
| | Query search + spatial indexes
| POST /on_discover (callback) |
| (matching resources + offers) |
|<-------------------------------------------|
```
### Example Use Case
A consumer opens a grocery shopping app and searches for "instant coffee near me". The Consumer Node (CN) sends a discover request to NFH fabric DISCOVR combining natural language text search with a spatial constraint (5 km radius around the consumer's location).
DISCOVR queries its search index for resources matching "instant coffee" and its spatial index for resources with availability locations within 5 km. The response includes multiple matching products from different providers — each with competing offers showing different prices, discounts, and delivery estimates.
The consumer compares offers and proceeds to order from the provider with the best price and fastest delivery.
### Design Principles
* **Real-time query engine**: Optimized for sub-second search — not for catalogue storage or signing (that's the publisher's role — see [Catalog Publishing and Discovery](/build/creating-a-network/catalog-publishing-and-discovery.md))
* **Crawler-fed**: Discovers and pulls catalogue updates directly from each provider's own storage on its own schedule — no polling of a central service, no manual sync
* **Verify-before-index**: Every catalogue index and file is checked against its publisher's Registry-registered signature and digest before anything is indexed
* **Multi-modal search**: Supports text, natural language, spatial, and structured attribute queries — individually or combined
* **Provider-agnostic**: Returns resources from all providers in a network, with competing offers side by side
* **Schema-aware**: Understands NFH fabric resource and offer schemas — filters, groups, and prunes results based on schema context
### API Reference
DISCOVR exposes one consumer-facing HTTP endpoint for running queries. Catalog data reaches DISCOVR's index via its own crawler, which pulls directly from each provider's self-hosted storage and indexes it via an internal `/catalog/push` API (see [Catalog indexing](#catalog-indexing) and [How DISCOVR Stays Updated](#how-discovr-stays-updated) below).
#### Discovery APIs (Consumer Node-facing)
| API | Method | Description |
| ----------- | ------ | ----------------------------------------------------------------------------------------------------- |
| `/discover` | POST | Asynchronous — acknowledges with `ACK`, delivers results via `POST /on_discover` callback to `bapUri` |
#### Catalog indexing
DISCOVR **implements** the `/catalog/push` endpoint that the crawler calls to deliver catalog updates matching an active subscription — the push leg of [How DISCOVR Stays Updated](#how-discovr-stays-updated). DISCOVR validates the push and responds **synchronously** with an NFH fabric `ACK` (accepted — indexed asynchronously and searchable via `/discover` shortly after) or `NACK`.
**What DISCOVR receives.** Each entry in `message.catalogs[]` is a **resolved** catalog, not the raw fragment a Provider Node published. For resources that extend a master (`masterResourceId`), the crawler merges the master into the overlay (master-wins) *before* pushing, so DISCOVR receives self-contained, indexable resources. DISCOVR does not re-resolve against masters — it indexes exactly what is pushed.
This endpoint's authentication, request/response shape, and status codes are not part of the Beckn protocol — `/catalog/push` here is an internal API between the Edge Discovery Service and its crawler, not a wire-level Beckn action. Nothing mandates using this same interface between the two: an implementation is free to wire its crawler to its own indexing layer however it chooses (a different internal API, an in-process call, or any other mechanism) — this section documents the shape this reference implementation happens to use.
#### Search Modes
| Mode | Description | Example |
| --------------------------- | ------------------------------------------------------ | ----------------------------------- |
| **Text / Natural Language** | Keyword or conversational query | "strong Assam tea for morning chai" |
| **Spatial** | Find resources near a location | Within 5 km of a GPS coordinate |
| **Attribute Filter** | Fine-grained filtering on resource or offer attributes | Flat discount offers under ₹100 |
| **Combined** | Mix any of the above in a single request | Coffee search within 5 km radius |
For detailed request/response formats and examples, see [Usage](/product-documentation/products/discovr/usage.md) and [Examples](/product-documentation/products/discovr/examples.md).
#### How DISCOVR Stays Updated
Reference Discovery service ships with a crawler, which helps the service to keep its indexes current with the decentralised catalogs.
1. DISCOVR's crawler resolves each provider's Registry manifest and Subscriber record, filtered to the `networkIds` and/or `schemaTypes` it cares about, and finds the catalog index url
2. It fetches the provider's catalogue index over HTTPS and verifies the index's signature against the provider's Registry-registered key
3. It compares the index's `entryVersion` against its own stored cursor for that catalogue — an unchanged entry is skipped without any further fetch
4. For a changed entry, it fetches only the baseline or change files the cutover rule calls for, verifies each file's signature and digest, and applies upserts/removals into its own index
5. The updated data is immediately searchable via `POST /discover`
There is no separate bulk "initial sync" call — a brand-new crawl and a routine re-crawl are the same operation; a crawler simply starts from no cursor the first time, so it fetches a provider's full baseline rather than an incremental change file. See [Catalog Publishing and Discovery → Hosting & Discovery](/build/creating-a-network/catalog-publishing-and-discovery.md#hosting--discovery) for the full crawl sequence and verification rules a provider can expect DISCOVR to apply.
## The NFH fabric capability: Discovery
DISCOVR realises the NFH fabric **Discovery** capability — network-wide search across every catalogue on NFH fabric: offerings, providers, credentials, and capabilities.
**What it gives you**
* **Network-wide search** — one query, every catalogue.
* **Structured filters** — by category, geography, provider type, credential, price.
* **Agent-native queries** — discovery exposed as MCP tools for autonomous agents.
* **Federated indexes** — operators can run sector- or geography-specific indexes that compose into the global surface.
**Where it sits** — a service NFH runs (the indexed discovery surface that consumes Cataloguing), the protocol NFH defines (query and response schemas), and reference software NFH publishes (discovery clients and agent integrations).
**Standards alignment:** MCP for agent-native discovery · open query APIs.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.nfh.global/product-documentation/products/discovr.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
