Skip to main content
Guppy is not URL-driven. Instead, partners use Resolve endpoints to turn human-friendly input (names, locations, constraints) into canonical IDs that Guppy can reliably execute against. The standard integration pattern is:
  1. Resolve candidates (products / venues / facilities)
  2. Select a candidate (user confirmation or programmatic choice)
  3. Create an intent referencing the canonical ID (e.g., product_id, venue_id, facility_id)

​
Resolve a product

POST /resolve/products Return canonical product candidates (optionally across multiple merchants).

​
Request Body

​
query
string
required
Human-friendly query like “PS5 Pro” or a model name.
​
identifiers
object
Optional identifiers like GTIN/UPC/SKU.
​
allowed_merchants
array
Optional allowlist of merchants (e.g., ["target", "bestbuy", "walmart"]).
​
limit
integer
Maximum number of candidates to return.

​
Example

{
  "query": "PS5 Pro",
  "allowed_merchants": ["target", "bestbuy", "walmart"],
  "limit": 5
}

​
Response (example)

{
  "candidates": [
    {
      "product_id": "prod_ps5pro_us_001",
      "name": "PlayStation 5 Pro Console",
      "identifiers": { "gtin": "…" },
      "merchant_coverage": ["target", "bestbuy", "walmart"]
    }
  ]
}

​
Resolve a restaurant/venue

POST /resolve/venues Return canonical venue candidates for reservations.

​
Request Body

​
query
string
required
Venue name or partial name (e.g., “Nopa”).
​
location
object
required
Location constraint.
​
location.city
string
City name (recommended if you don’t have lat/lng).
​
location.lat
number
Latitude for geo search.
​
location.lng
number
Longitude for geo search.
​
location.radius_miles
number
Search radius in miles (required for lat/lng searches).
​
allowed_providers
array
Optional allowlist (e.g., ["resy", "opentable"]).

​
Example

{
  "query": "Nopa",
  "location": { "city": "San Francisco" },
  "allowed_providers": ["resy", "opentable"]
}

​
Response (example)

{
  "candidates": [
    {
      "venue_id": "ven_sf_nopa_001",
      "provider": "resy",
      "name": "Nopa",
      "address": "…",
      "city": "San Francisco"
    }
  ]
}

​
Resolve an appointment facility

POST /resolve/appointment-facilities Return canonical facilities for appointment-based intents (passport, DMV, etc.).

​
Request Body

​
kind
string
required
Appointment kind (e.g., passport, dmv).
​
country
string
Country code (e.g., US).
​
location
object
required
Location constraint (geo or city/state).
​
location.lat
number
Latitude.
​
location.lng
number
Longitude.
​
location.radius_miles
number
Radius in miles.
​
allowed_providers
array
Optional allowlist of providers relevant to the kind (varies by region).

​
Example

{
  "kind": "passport",
  "country": "US",
  "location": { "lat": 37.7749, "lng": -122.4194, "radius_miles": 30 }
}

​
Response (example)

{
  "candidates": [
    {
      "facility_id": "fac_us_passport_sf_003",
      "name": "USPS – Main Post Office",
      "address": "…",
      "provider": "usps"
    }
  ]
}