Skip to main content

​
Current v1 Notes (Migration Phase)

  • Guppy Consumer first: During v1, the primary client is the Guppy consumer extension. The API surface is being hardened before third-party partner onboarding.
  • Purchase only: type=purchase is supported in v1.
  • URL-based objective (v1): For v1, objective.product.product_url is supported to bridge to Guppy’s existing monitoring system. Future versions will prefer canonical product_id from Resolve.
  • Idempotency: Writes support Idempotency-Key and replay successful (2xx) responses for 24 hours.

​
Create an Intent

POST /intents Create a new long‑lived commerce intent.

​
Request Body

​
external_user_id
string
required
The unique identifier for the user in your platform.
​
type
string
required
The type of intent. Currently supported: purchase, reservation.
​
objective
object
required
The goal of the intent.
​
conditions
object
Conditions that must be met for execution.
​
guardrails
object
Constraints on execution (max price, merchants, expiration).

​
Example Request

{
  "external_user_id": "user_123",
  "type": "purchase",
  "objective": {
    "product": {
      "product_url": "https://www.target.com/p/...",
      "product_title": "PS5 Pro",
      "product_image_url": "https://..."
    },
    "quantity": 1
  },
  "conditions": {
    "max_price_cents": 80000,
    "currency": "USD",
    "availability": "in_stock"
  },
  "guardrails": {
    "allowed_merchants": ["target"],
    "expires_at": "2026-02-01T00:00:00Z",
    "retry_policy": "safe"
  },
  "metadata": {
    "agent": "hunter_v2"
  }
}

​
Response

{
  "intent_id": "int_789",
  "status": "active",
  "created_at": "2026-01-11T20:12:00Z"
}

​
Intent Lifecycle

Guppy automatically transitions intents based on real‑world conditions.
  • active: Monitoring conditions.
  • waiting: Conditions not yet met.
  • executing: Currently performing actions.
  • requires_user_action: Input needed from user (e.g., OTP).
  • succeeded: Goal achieved.
  • failed: Terminal failure.
  • expired: Time limit reached.
  • canceled: Canceled by developer/user.

​
Get Intent

GET /intents/{intent_id} Returns current state and latest execution summary.

​
Cancel Intent

POST /intents/{intent_id}/cancel Stops monitoring and execution.

​
Resume Intent

POST /intents/{intent_id}/resume Resume an intent that is in the requires_user_action state.