> ## Documentation Index
> Fetch the complete documentation index at: https://docs.liquidrewardsapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

This guide walks through making your first product search, fetching full product details, and paginating results.

## Prerequisites

* An API key. See [Authentication](/authentication).
* A tool to make HTTP requests (curl, Postman, or your language of choice).

<Steps>
  <Step title="Search for products">
    Send a `POST` request to `/v1/discovery/products/search` with a free-text query and optional structured filters.

    ```bash theme={null}
    curl https://rewardsbot-prod.liquidrewardsapi.com/v1/discovery/products/search \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "query": "running shoes",
        "criteria": [
          { "field": "on_sale",  "operator": "=", "value": true },
          { "field": "in_stock", "operator": "=", "value": true }
        ],
        "per_page": 25
      }'
    ```

    The response includes `items`, `page_index`, `page_size`, and a `next_cursor` for the next page.
  </Step>

  <Step title="Paginate to the next page">
    Pass the `next_cursor` from the previous response back as `cursor` to fetch the next page. No other fields are required when paginating.

    ```bash theme={null}
    curl https://rewardsbot-prod.liquidrewardsapi.com/v1/discovery/products/search \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "cursor": "opaque-next-page-cursor" }'
    ```

    <Note>
      Cursors and their backing search sessions expire. A `410` response means you need to start a new search.
    </Note>
  </Step>

  <Step title="Get full product details">
    Each search result includes a `slug`. Use it to fetch full product details, including pricing, brand, merchant, and availability.

    ```bash theme={null}
    curl https://rewardsbot-prod.liquidrewardsapi.com/v1/discovery/products/PRODUCT_SLUG \
      -H "x-api-key: YOUR_API_KEY"
    ```
  </Step>

  <Step title="Reuse filters with criteria sets">
    Save commonly-used filter bundles as **criteria sets** and apply them by ID on future searches.

    ```bash theme={null}
    curl https://rewardsbot-prod.liquidrewardsapi.com/v1/discovery/products/criteria-sets \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "id": "summer-sale",
        "name": "Summer Sale",
        "criteria": [
          { "field": "on_sale",       "operator": "=",  "value": true },
          { "field": "sale_discount", "operator": ">=", "value": 0.2 }
        ]
      }'
    ```

    Then reference it from a search:

    ```json theme={null}
    {
      "query": "sandals",
      "criteria_set_ids": ["summer-sale"]
    }
    ```
  </Step>
</Steps>

## Next steps

* Browse the full [API Reference](/api-reference) for every endpoint, parameter, and schema.
* Explore the catalog of available filter fields and operators in the search request schema.