Conversations

A stateful, conversational search. The Plugie AI decides when to run local searches and appends the results as messages in a conversation you poll. It's persistent: if nothing turns up, it widens the area and keeps looking. For a one-shot synchronous list, use Search instead.

Requires an API key and a location. See Base URL & authentication.

How it works

Start a conversation — you get back a conversation URL, not results.
Poll that URL to read new messages. Assistant messages carry a structured results payload you can render as a browsable carousel.
Continue by posting follow-up messages, or paginate the last results.
Empty searches schedule a widened retry — poll to pick up the later message when it lands.

Start a conversation

POST/v1/conversations

Field	Type	Description
queryrequired	string	The shopper's request, in any language.
target	string	Optional hint — `products` or `stores`. The agent may override it.
lat, lng / city		Compulsory location (coordinates or a city), scoped optionally by country.
country	string	Restrict to sellers serving this country.

curl

curl https://api.plugie.ai/v1/conversations \
  -H "Authorization: Bearer plg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "query": "een bureaustoel onder de 200 euro", "city": "Amsterdam" }'

json

{ "conversationId": "66aa…", "url": "https://api.plugie.ai/v1/conversations/66aa…", "locatedBy": "city" }

Poll the conversation

GET/v1/conversations/:id

Returns the conversation and its messages. Poll it to render new messages as they arrive.

json

{
  "conversation": { "id": "66aa…", "status": "active", "target": "products", "radiusKm": 1 },
  "messages": [
    { "role": "user", "text": "een bureaustoel onder de 200 euro" },
    {
      "role": "assistant",
      "text": "Here are some office chairs near you!",
      "results": {
        "target": "products",
        "data": [ { "id": "665f…", "title": "Aero Ergonomic Office Chair", "price": { "amount": 18900, "currency": "EUR" }, "distanceKm": 2.4, "remote": false, "store": { "slug": "techworld" } } ],
        "remote": [],
        "meta": { "page": 1, "pageSize": 20, "hasMore": false, "radiusKm": 1 }
      }
    }
  ]
}

conversation.status is active (has results / awaiting you), waiting (a widened retry is scheduled — keep polling), or done.

Continue & paginate

POST/v1/conversations/:id/messages

Send a follow-up; the agent runs another turn. Body: { "text": "cheaper ones?" }.

POST/v1/conversations/:id/paginate

Page the most recent results. Body: { "direction": "next" | "prev" }.

Both return the updated conversation, so you can re-render immediately without a separate poll.

Notes

The results payload matches Search (same item shapes + remote tier), so one renderer serves both.
Widened retries step the radius up a ladder and stop at a cap — polling is how clients see them today; realtime/webhooks are planned.
Queries work in any language; results are matched semantically against the (multilingual) catalog.