Intents

​

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

​

Request Body

​

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

• 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

​

Cancel Intent

​

Resume Intent