> ## 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.

# Discovery API Overview

> Find and discover products across merchant catalogs

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

## Available Endpoints

<CardGroup cols={2}>
  <Card title="Search Products" icon="magnifying-glass" href="/api-reference/discovery/search">
    Search for products using keywords with filters for domains, price, availability, and variant attributes
  </Card>

  <Card title="Get Search Options" icon="sliders" href="/api-reference/discovery/options">
    Retrieve available filter options for building search filter UIs
  </Card>
</CardGroup>

## 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](/api-reference/catalog/overview)** 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:

| Method                                                             | Use Case                                     | Headers                                         |
| ------------------------------------------------------------------ | -------------------------------------------- | ----------------------------------------------- |
| [Browser Session](/api-reference/authentication/browser-session)   | Client-side apps (browser, mobile)           | `x-firmly-authorization`                        |
| [Server-to-Server](/api-reference/authentication/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 **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.