> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guppyapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Intents

> Manage the lifecycle of commerce 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

`POST /intents`

Create a new long‑lived commerce intent.

### Request Body

<ParamField body="external_user_id" type="string" required>
  The unique identifier for the user in your platform.
</ParamField>

<ParamField body="type" type="string" required>
  The type of intent. Currently supported: `purchase`, `reservation`.
</ParamField>

<ParamField body="objective" type="object" required>
  The goal of the intent.

  <Expandable title="objective properties">
    <ParamField body="product" type="object">
      Information about the product.

      <Expandable title="product properties">
        <ParamField body="product_url" type="string">
          (v1) Product URL to monitor/execute against (extension-based execution bridge).
        </ParamField>

        <ParamField body="product_title" type="string">
          Optional display title (v1).
        </ParamField>

        <ParamField body="product_image_url" type="string">
          Optional display image URL (v1).
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="quantity" type="integer">Number of items.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="conditions" type="object">
  Conditions that must be met for execution.
</ParamField>

<ParamField body="guardrails" type="object">
  Constraints on execution (max price, merchants, expiration).
</ParamField>

### Example Request

```json theme={null}
{
  "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

```json theme={null}
{
  "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.