Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. API Reference
  3. Discovery

Discovery

The Firmly Discovery APIs help users find products across multiple merchant catalogs. These APIs power product search and filtering capabilities.

​​ Available Endpoints

Search Products Search for products using keywords with filters for domains, price, availability, and variant attributes Search Products by Query Lightweight keyword search across configured merchant catalogs, by query string

​​ Key Concepts

​​ Discovery vs Catalog APIs

Discovery APIs Catalog APIs
Search across multiple merchants Query a specific merchant
Keyword search with filters Direct product retrieval
Filters and facets Exact lookups by handle/URL
Aggregated product data Real-time merchant data

Use Discovery APIs when:

  • Users are browsing or searching for products
  • You need to show products from multiple merchants
  • You want to filter by price, availability, or variants

Use Catalog APIs when:

  • You know the exact product and merchant
  • You need real-time availability/pricing
  • You’re building a product detail page for a specific merchant

​​ Typical Search Flow 


1. User enters search query and selects filters
        ↓
2. Search products (POST /api/v1/discovery/search)
        ↓
3. Display results with previews
        ↓
4. User selects a product
        ↓
5. Catalog API fetches full product details
        ↓
6. Cart API adds item to cart

Filter facets for the UI come from the filter_options block in the Search response (returned on the first page): variant options, domains, price range, and in-stock count, each with counts.

​​ Authentication

Discovery endpoints support three authentication methods:

Method Use Case Headers
Browser Session Client-side apps (browser, mobile) x-firmly-authorization
App ID Trusted server-side clients that don’t need a per-device session x-firmly-app-id
Server-to-Server Backend services acting on behalf of devices x-firmly-authorization + x-firmly-device-id

Choose Browser Session for direct client integrations. Choose App ID for trusted server-side clients that don’t need a per-device session. Choose Server-to-Server when your backend needs to make Discovery API calls on behalf of a user’s device. See Search Products for the per-method request examples.

​​ Domain Authorization

Search results are limited to merchant domains associated with your account. Contact your account manager to request access to additional merchants.

​​ Rate Limits

Discovery APIs are subject to Firmly’s standard rate limits. Contact support for higher limits if needed for production workloads.