---
title: "Search products"
method: POST
path: "/agent/search"
tags: ["Products"]
---

# Search products

`POST /agent/search`

## Request

- Base URL: `https://api.trusteed.xyz/api/v1`
- URL: `https://api.trusteed.xyz/api/v1/agent/search`
- Auth: API key in header `X-Agent-Api-Key`

Search products across eligible merchants (verificationLevel BASIC+, trustScore ≥0.3, not suspended). Ranking: text_relevance×0.55 + store_trust_score×0.25 + freshness×0.10 + in_stock×0.10.

## Request body

- SearchRequest
  - `query` string, required
  - `filters` object
    - `minPrice` number
    - `maxPrice` number
    - `category` string
    - `inStock` boolean
    - `minTrustScore` number
    - `verificationLevel` 'BASIC' | 'STANDARD' | 'PREMIUM' | 'QUALIFIED'
  - `sort` 'relevance' | 'price_asc' | 'price_desc' | 'trust_score' | 'newest'
  - `page` integer
  - `limit` integer: Server caps the effective limit at 100 regardless of the value sent.
  - `deduplicate` boolean: Read directly from the raw body (not part of the validated schema) — collapses near-duplicate titles across merchants, keeping the highest-scoring result.

## Response `200`

Successful search response

- SearchResponse
  - `success` true, required
  - `data` object, required
    - `products` ProductSummary[], required
      - `id` string, uuid, required
      - `title` string, required
      - `description` string, required
      - `price` number, required
      - `compareAtPrice` number, nullable, required
      - `currency` string, required
      - `inStock` boolean, required
      - `imageUrl` string, nullable, required
      - `category` string, nullable, required
      - `merchant` MerchantSummary, required
        - `slug` string, required
        - `name` string, required
        - `trustScore` number, nullable, required
        - `verificationLevel` 'UNVERIFIED' | 'BASIC' | 'STANDARD' | 'PREMIUM', required
        - `storeStatus` 'active' | 'deprioritized', required
        - `lastSyncAt` string, date-time, nullable
      - `relevanceScore` number, required
      - `freshnessTier` 'fresh' | 'good' | 'stale' | 'very_stale' | 'unknown', required
      - `stockConfidence` 'high' | 'medium' | 'low', required
      - `priceConfidence` 'high' | 'medium' | 'low', required
      - `why_ranked` string, required: Human-readable explanation of ranking
      - `euQualified` boolean, required
    - `meta` object, required
      - `total` integer, required
      - `page` integer, required
      - `limit` integer, required
      - `totalPages` integer, required
    - `queryMeta` object, required
  - `meta` object

## Other responses

- `400`: Bad request

---

[API](https://skmtc.dev/trusteed/apis/trusteed-api.md) · [All operations](https://skmtc.dev/trusteed/apis/trusteed-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trusteed/apis/trusteed-api/revisions/14ce607accce?raw)