Public shopping agent protocol

Exact finds, with the evidence still attached.

Use SwapMeet’s public API when a buyer has a specific item in mind. Every returned result comes from current marketplace inventory and carries a stable detail link, its original source, a last-checked timestamp, seller declaration, transaction mode, and an explanation of the match.

One endpoint

GET /api/agent-search

POST accepts the same structured fields when query parameters are inconvenient.

Inspect endpoint

Request shape

State the buyer’s boundaries.

Item criteria, a resolvable U.S. city/ZIP/state, one supported radius, and an explicit cash-versus-trade mode are required. Optional category, condition, price, and seller filters remain exact filters.

{
  "protocolVersion": "1",
  "itemCriteria": "vintage road bike",
  "location": "Seattle, WA",
  "radiusMiles": 25,
  "mode": "either"
}

No geography drift

The submitted U.S. place is resolved, then the inclusive Haversine radius is applied. No wider fallback location is returned.

Fresh only

Results require a public, source-backed listing with an explicit fresh status and a persisted last-checked timestamp.

Honest states

ready returns matches; empty means none matched; stale means matching inventory exists but fresh evidence is unavailable.

Response contract

Follow stable state to a listing.

Use searchId andcanonicalSearchUrl to preserve the exact search state.

Each result includes listingUrl at /listings/:id and a directsourceUrl. Use the returned sourceClickUrl only when the buyer deliberately wants measured source attribution.

Do not turn stale orempty into alternatives: SwapMeet does not broaden item criteria, radius, or geography silently.

Optional measurement

Record useful intent, not bot traffic.

After a successful search, an agent may POST the exact criteria, searchId, listingId, and listing_opened to/api/agent-events. Source attribution is separately opt-in through the returned sourceClickUrl. Both paths revalidate the search and listing before recording API-event evidence.