Search

Run an AI-powered product search across Plugie's seller catalogs and get back ranked matches. This is the same engine that powers the buyer app, exposed for you to call from your own apps and websites.

POST/v1/search

Send a natural-language query; Plugie parses it into structured intent (product type, budget, location, constraints), finds candidate products, filters by where they can be sold, resolves prices, and ranks the results with AI. The call is stateless — nothing is saved, and each request returns a fresh result set.

Requires an API key. See Base URL & authentication for how to create one and pass it as a Bearer token.

Request body

A JSON object with the following fields:

Field	Type	Description
queryrequired	string	The shopper's request in plain language, e.g. `"black office chair under €200"`. 1–500 characters.
rankingMode	string	How to rank results: `balanced` (default), `cheapest`, `closest`, or `best_quality`.
country	string	Buyer country (name or ISO code). Filters out products not sold there and resolves prices for that region. Defaults to any country inferred from `query`.
currency	string	Preferred ISO-4217 currency for resolved prices, e.g. `EUR`. Falls back to each product's default.
limit	number	Maximum number of results to return, 1–50. Defaults to `12`.

Example request

curl

curl https://api.plugie.ai/v1/search \
  -H "Authorization: Bearer plg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "black leather office chair under €200",
    "rankingMode": "balanced",
    "country": "Germany",
    "currency": "EUR",
    "limit": 5
  }'

Node.js (fetch)

const res = await fetch("https://api.plugie.ai/v1/search", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.PLUGIE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "black leather office chair under €200",
    country: "Germany",
    limit: 5,
  }),
});
const data = await res.json();
console.log(data.results);

Response

Returns 200 OK with the parsed query and the ranked matches.

Field	Type	Description
query	string	The query you sent, echoed back.
title	string	A short human-readable name for the search, derived from the query.
rankingMode	string	The ranking mode applied.
checked	number	How many candidate listings were evaluated.
count	number	Number of results returned.
results	array	The ranked matches, best first. See Result object below.

Result object

Field	Type	Description
productId	string	Unique id of the matched product.
title	string	Product title.
description	string	Product description, if any.
price	object	Resolved price as `{ amount, currency }`. `amount` is in the currency's minor units (e.g. cents), so `19900` means €199.00. May be omitted if the product has no resolvable price.
image	string	URL of the product's primary image, if any.
store	object	The selling store as `{ id, name, slug }`. Use `slug` to link to its storefront.
matchScore	number	Composite relevance score from 0 to 1 — higher is a stronger match.
rationale	string	A short AI explanation of why the product matched.

Example response

json

{
  "query": "black leather office chair under €200",
  "title": "Black leather office chair under €200",
  "rankingMode": "balanced",
  "checked": 34,
  "count": 2,
  "results": [
    {
      "productId": "665f1c2a9d1e4b0012a3c4d5",
      "title": "Erro Ergonomic Leather Chair",
      "description": "High-back office chair in black leather.",
      "price": { "amount": 18900, "currency": "EUR" },
      "image": "https://cdn.plugie.ai/products/erro-chair.jpg",
      "store": { "id": "660a…", "name": "Nord Office", "slug": "nord-office" },
      "matchScore": 0.82,
      "rationale": "Black leather, ergonomic, and under the €200 budget."
    },
    {
      "productId": "665f1c2a9d1e4b0012a3c4e9",
      "title": "Deskline Task Chair",
      "price": { "amount": 14500, "currency": "EUR" },
      "image": "https://cdn.plugie.ai/products/deskline.jpg",
      "store": { "id": "661b…", "name": "WorkWell", "slug": "workwell" },
      "matchScore": 0.64,
      "rationale": "Comfortable and affordable, though not leather."
    }
  ]
}

Errors

Field	Type	Description
400	bad_request	The body failed validation — e.g. a missing `query` or an out-of-range `limit`.
401	unauthorized	Missing, malformed, or revoked API key. See authentication.

json

{
  "error": {
    "code": "bad_request",
    "message": "query is required"
  }
}

Notes

Results are ranked, not paginated — request more with limit (up to 50).
Each call runs the AI pipeline fresh; expect it to take a moment longer than a plain database query.
Prices are region-resolved: the same product may return different amounts for different country/currency values.