Skip to main content

​
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": {
      "name": "PS5 Pro",
      "identifiers": {"gtin": "…"}
    },
    "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"
  },
  "payment": {
    "payment_method_id": "pm_abc",
    "max_charge_cents": 82000
  },
  "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.