Search the catalog

Full-text search across products, brands, and retailers. Uses PostgreSQL websearch parsing (the same syntax as a Google query box — quoted phrases, -exclusions, and OR are honored) with ts_rank for relevance. Falls back to substring (icontains) matching when full-text returns no rows, so partial words like trai still surface relevant items.

Pass ?type= (repeatable) to limit the result set to a subset of resource collections. Results are merged across collections, ranked together, and truncated to limit.

Auth: unauthenticated (anonymous IP-throttled at 60 requests/minute).

GET /search/api/v1/search

Search the catalog

cURL

curl --request GET \
  --url https://www.closient.com/search/api/v1/search

200

{
  "query": "<string>",
  "total_count": 1,
  "results": [
    {
      "id": "<string>",
      "name": "<string>",
      "rank": 1,
      "description": "",
      "metadata": {},
      "certifications": [
        "<string>"
      ],
      "contains_allergens": [
        "<string>"
      ],
      "substance_flags": [
        "<string>"
      ],
      "allergen_data_confidence": "low"
    }
  ]
}

Query Parameters

q · string · required

Search query text. Supports quoted phrases ("trail mix"), exclusion (trail -mix), and OR operators.

Required string length: 1 - 255

type · enum<string>[]

Filter results to one or more resource collections. Repeat the parameter to include multiple (e.g. ?type=product&type=brand). Omit to search all three.

Resource types returned by the catalog search endpoint.

Each result row carries one of these in its type field. The GET /search endpoint accepts the same values via the repeated ?type= query parameter to filter results to a subset.

Available options: product, brand, retailer

limit · integer · default: 25

Maximum number of results to return. Capped at 100.

Required range: 1 <= x <= 100

exclude_allergens · string[]

Allergen slugs to drop (C-2961). Products whose contains_allergens intersect any value here are removed from the response. Repeat the parameter for multiple slugs (e.g. ?exclude_allergens=peanuts&exclude_allergens=tree_nuts). Accepts the same vocabulary as the session-based constraint extractor.

require_certifications · string[]

Certification slugs the product must hold (C-2961). A product is dropped if any required slug is missing from its certifications. Repeat the parameter for multiple slugs. Brand/retailer rows are passed through unchanged.

avoid_substances · string[]

Substance slugs to drop (C-2961). Matched substances surface inline in each remaining row's substance_flags when present, so callers can build 'flagged because X' UI affordances. Repeat for multiple.

Response

200 - application/json

OK

Response envelope for GET /search.

Wraps the matched rows with the original query and a result count. Results are pre-sorted by rank descending. total_count reports the size of the returned list, not the size of the corpus — this endpoint truncates to limit and does not paginate.

query · string · required

The search query that was executed (echoed back for client-side correlation).

total_count · integer · required

Number of results in this response. Always equals len(results).

Required range: x >= 0

results · CatalogSearchResultOut · object[]

Matched rows sorted by rank descending.

Show child attributes