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=purchaseis supported in v1. - URL-based objective (v1): For v1,
objective.product.product_urlis supported to bridge to Guppy’s existing monitoring system. Future versions will prefer canonicalproduct_idfrom Resolve. - Idempotency: Writes support
Idempotency-Keyand replay successful (2xx) responses for 24 hours.
Create an Intent
POST /intents
Create a new long‑lived commerce intent.
Request Body
Example Request
Response
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.