Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.firmly.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

Get Search Options

Retrieve available filter options for building search filter UIs

​
Key Concepts

​
Discovery vs Catalog APIs

Discovery APIsCatalog APIs
Search across multiple merchantsQuery a specific merchant
Keyword search with filtersDirect product retrieval
Filters and facetsExact lookups by handle/URL
Aggregated product dataReal-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. Fetch variant options (GET /options)
        ↓
2. User enters search query and selects filters
        ↓
3. Search products (POST /search)
        ↓
4. Display results with previews
        ↓
5. User selects a product
        ↓
6. Catalog API fetches full product details
        ↓
7. Cart API adds item to cart

​
Authentication

Discovery endpoints support two authentication methods:
MethodUse CaseHeaders
Browser SessionClient-side apps (browser, mobile)x-firmly-authorization
Server-to-ServerBackend services acting on behalf of devicesx-firmly-authorization + x-firmly-device-id
Choose Browser Session for direct client integrations. Choose Server-to-Server when your backend needs to make Discovery API calls on behalf of a user’s device.

​
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 standard rate limits. Contact support for higher limits if needed for production workloads.