Examples

This page shows practical, end-to-end examples of how a partner would integrate Guppy for various workflows. Each example follows the same pattern:

Create an intent with objective + conditions + guardrails
Listen for events (webhook)
If needed, handle user action required
Read the result (and optionally fetch receipt/proof)

Example 1: Buy an item across retailers (below price by date)

Goal: “Buy PS5 Pro if it’s in stock at Target/BestBuy/Walmart for under $800, any time before Feb 1.”

Step 1 - Resolve product (no URLs)

POST /resolve/products
Authorization: Bearer GUPPY_SECRET_KEY
Content-Type: application/json

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

Pick a product_id from the returned candidates (optionally confirm with the user).

Step 2 - Create intent

POST /intents
Authorization: Bearer GUPPY_SECRET_KEY
Content-Type: application/json
Idempotency-Key: buy_user123_ps5pro_under800_before_2026-02-01

{
  "external_user_id": "user_123",
  "type": "purchase",
  "objective": {
    "product": {
      "product_id": "prod_ps5pro_us_001",
      "quantity": 1
    }
  },
  "conditions": {
    "availability": "in_stock",
    "max_price_cents": 80000,
    "currency": "USD"
  },
  "guardrails": {
    "allowed_merchants": ["target", "bestbuy", "walmart"],
    "expires_at": "2026-02-01T00:00:00Z",
    "retry_policy": "safe"
  },
  "payment": {
    "payment_method_id": "pm_...",
    "max_charge_cents": 82000
  },
  "metadata": {
    "source": "assistant_v1"
  }
}

Typical event sequence

{ "type": "intent.created", "intent_id": "int_..." }

{
  "type": "intent.waiting",
  "intent_id": "int_...",
  "data": { "reason": "OUT_OF_STOCK" }
}

{ "type": "intent.executing", "intent_id": "int_..." }

If checkout requires an OTP/3DS confirmation:

{
  "type": "execution.needs_user_action",
  "intent_id": "int_...",
  "data": {
    "action_type": "otp",
    "instructions": "Enter the code sent to your phone to confirm the purchase."
  }
}

Partner prompts the user, then resumes:

POST /intents/int_.../resume
Authorization: Bearer GUPPY_SECRET_KEY
Content-Type: application/json

{
  "user_action": {
    "type": "otp",
    "completed": true
  }
}

Finally:

{
  "type": "intent.succeeded",
  "intent_id": "int_...",
  "data": {
    "purchase": {
      "merchant": "target",
      "total_charged_cents": 79999,
      "currency": "USD"
    }
  }
}

Example 2: Restaurant reservation (watch cancellations)

Goal: “Table for 4 Fri or Sat between 7–9pm. Watch cancellations. Give up if not confirmed by Thursday.”

Step 1 - Resolve venue (no URLs)

POST /resolve/venues
Authorization: Bearer GUPPY_SECRET_KEY
Content-Type: application/json

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

Pick a venue_id (and provider) from the returned candidates.

Step 2 - Create intent

{
  "external_user_id": "user_123",
  "type": "reservation",
  "objective": {
    "reservation": {
      "provider": "resy",
      "venue_id": "ven_sf_nopa_001",
      "party_size": 4
    }
  },
  "conditions": {
    "time_windows": [
      {
        "start": "2026-01-16T19:00:00-08:00",
        "end": "2026-01-16T21:00:00-08:00"
      },
      {
        "start": "2026-01-17T19:00:00-08:00",
        "end": "2026-01-17T21:00:00-08:00"
      }
    ]
  },
  "guardrails": {
    "expires_at": "2026-01-15T23:59:00-08:00",
    "retry_policy": "safe"
  }
}

Example 3: Passport / DMV appointment (earliest slot within 30 miles)

Goal: “Book the earliest appointment within 30 miles. Keep watching cancellations until booked.”

Step 1 - Resolve facilities (no URLs)

POST /resolve/appointment-facilities
Authorization: Bearer GUPPY_SECRET_KEY
Content-Type: application/json

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

Pick a facility_id from the returned candidates.

Step 2 - Create intent

{
  "external_user_id": "user_123",
  "type": "reservation",
  "objective": {
    "appointment": {
      "kind": "passport",
      "facility_id": "fac_us_passport_sf_003"
    }
  },
  "conditions": {
    "date_range": { "start": "2026-01-13", "end": "2026-02-28" },
    "strategy": "earliest_available"
  },
  "guardrails": {
    "expires_at": "2026-02-28T23:59:59Z",
    "retry_policy": "safe"
  }
}

What the partner app does

Listen for execution.needs_user_action to collect missing identity fields or confirmations.
Once intent.succeeded arrives, show the user the booked slot.
Optionally fetch proof:

GET /intents/int_.../receipt
Authorization: Bearer GUPPY_SECRET_KEY

Example 4: SMB replenishment (avoid double ordering, net terms)

Goal: “Reorder when inventory < 10. Net-30 only.”

Create intent

POST /intents
Idempotency-Key: replenish_sku_coffee_5lb_threshold_10

{
  "external_user_id": "biz_456",
  "type": "purchase",
  "objective": {
    "procurement": {
      "item": { "name": "Coffee Beans 5lb", "sku": "coffee_5lb" },
      "quantity": 2
    }
  },
  "conditions": {
    "trigger": {
      "kind": "inventory_below",
      "sku": "coffee_5lb",
      "threshold": 10
    }
  },
  "guardrails": {
    "retry_policy": "safe"
  },
  "payment": {
    "billing_terms": "net-30"
  },
  "metadata": {
    "inventory_system": "erp",
    "warehouse": "sf_warehouse"
  }
}

What the partner app does

De-dupe create calls with Idempotency-Key so a retry can’t create duplicate orders.
Use webhook events to update internal order state (pending → executing → succeeded).
On success, fetch receipt/proof for accounting:

GET /intents/int_.../receipt
Authorization: Bearer GUPPY_SECRET_KEY

Integration checklist (what you build on your side)

API client: call POST /intents, GET /intents/{id}, POST /intents/{id}/cancel, POST /intents/{id}/resume
Webhook receiver: store event_id for de-duplication and update intent state
User-action UI: handle execution.needs_user_action and call resume
Receipt storage: download/store proof artifacts when needed (support, disputes, compliance)

Getting Started

Capabilities

Reliability

Example 1: Buy an item across retailers (below price by date)

Step 1 - Resolve product (no URLs)

Step 2 - Create intent

Typical event sequence

Example 2: Restaurant reservation (watch cancellations)

Step 1 - Resolve venue (no URLs)

Step 2 - Create intent

Example 3: Passport / DMV appointment (earliest slot within 30 miles)

Step 1 - Resolve facilities (no URLs)

Step 2 - Create intent

What the partner app does

Example 4: SMB replenishment (avoid double ordering, net terms)

Create intent

What the partner app does

Integration checklist (what you build on your side)

​Example 1: Buy an item across retailers (below price by date)

​Step 1 - Resolve product (no URLs)

​Step 2 - Create intent

​Typical event sequence

​Example 2: Restaurant reservation (watch cancellations)

​Step 1 - Resolve venue (no URLs)

​Step 2 - Create intent

​Example 3: Passport / DMV appointment (earliest slot within 30 miles)

​Step 1 - Resolve facilities (no URLs)

​Step 2 - Create intent

​What the partner app does

​Example 4: SMB replenishment (avoid double ordering, net terms)

​Create intent

​What the partner app does

​Integration checklist (what you build on your side)

Example 1: Buy an item across retailers (below price by date)

Step 1 - Resolve product (no URLs)

Step 2 - Create intent

Typical event sequence

Example 2: Restaurant reservation (watch cancellations)

Step 1 - Resolve venue (no URLs)

Step 2 - Create intent

Example 3: Passport / DMV appointment (earliest slot within 30 miles)

Step 1 - Resolve facilities (no URLs)

Step 2 - Create intent

What the partner app does

Example 4: SMB replenishment (avoid double ordering, net terms)

Create intent

What the partner app does

Integration checklist (what you build on your side)