Skip to main content
POST
/
v0
/
user
/
ipa
Example payload
{
  "raw_intent": "Buy AirPods Pro 2",
  "intent_type": "product",
  "autonomy_level": "auto_within_conditions",
  "constraints": {
    "max_price": 200,
    "currency": "GBP",
    "extra": {"brands": ["Apple"], "item_conditions": ["new"]}
  },
  "conditions": [
    {
      "type": "price_target",
      "operator": "lte",
      "target_price": 180,
      "currency": "GBP"
    }
  ]
}
{
  "_links": {},
  "intent": {
    "id": "<string>",
    "intent_type": "product",
    "status": "qualifying",
    "autonomy_level": "supervised",
    "created_at": 123,
    "raw_intent": "<string>",
    "specification": "<string>",
    "constraints": {
      "max_price": 123,
      "max_total": 123,
      "currency": "<string>",
      "deadline": 123,
      "preferred_sellers": [
        "<string>"
      ],
      "excluded_sellers": [
        "<string>"
      ],
      "extra": {}
    },
    "preflight_workflow_id": "<string>",
    "conditions": [
      {
        "operator": "lte",
        "target_price": "<string>",
        "type": "price_target",
        "currency": "USD"
      }
    ],
    "monitor_until": 123,
    "clarification_questions": [
      "<string>"
    ],
    "failure_reason": "<string>",
    "pint_uris": [
      "<string>"
    ],
    "updated_at": 123,
    "completed_at": 123,
    "originating_agent_task": {
      "id": "<string>",
      "status": "<string>",
      "trigger_type": "<string>",
      "created_at": 123,
      "workflow_run_id": "<string>",
      "task": "<string>",
      "title": "<string>",
      "started_at": 123,
      "completed_at": 123
    },
    "executing_agent_task": {
      "id": "<string>",
      "status": "<string>",
      "trigger_type": "<string>",
      "created_at": 123,
      "workflow_run_id": "<string>",
      "task": "<string>",
      "title": "<string>",
      "started_at": 123,
      "completed_at": 123
    },
    "candidates": [
      {
        "id": "<string>",
        "offer_id": "<string>",
        "status": "<string>",
        "created_at": 123,
        "rank": 123,
        "score": 123,
        "rejection_reason": "<string>"
      }
    ],
    "manifests": [
      {
        "id": "<string>",
        "status": "<string>",
        "items": [
          {
            "offer_id": "<string>",
            "quantity": 123,
            "unit_price_amount": "<string>",
            "unit_price_asset": "<string>"
          }
        ],
        "created_at": 123,
        "total_amount": "<string>",
        "total_asset": "<string>",
        "approved_at": 123,
        "purchased_at": 123
      }
    ],
    "events": [
      {
        "id": "<string>",
        "event_type": "ipa.status_change",
        "created_at": 123,
        "payload": "<string>"
      }
    ]
  }
}

Headers

Idempotency-Key
string | null
x-juno-orgid
string | null

Tenant org ID for multi-tenant auth

x-sumvin-token
string | null
x-juno-jwt
string | null
x-sumvin-pint-token
string | null

Body

application/json

Create a new IPA from a natural-language purchase request.

  • raw_intent preserves the original user request for auditability and re-parsing.
  • constraints define what acceptable purchase options must satisfy (selection filters and guardrails).
  • conditions define when an approved IPA may auto-execute (monitoring/automation triggers).

Use constraints for search and validation guardrails. Use conditions for execution triggers.

Example: constraints.max_price = 200 means results above 200 should not be proposed. conditions[].target_price = 180 means the system may wait and auto-execute if price later drops below 180.

raw_intent
string
required

Raw user request in natural language. Preserved exactly as submitted for auditability and re-parsing.

Required string length: 1 - 2000
Example:

"Buy AirPods Pro under £180 and wait up to 2 weeks."

intent_type
enum<string>
default:product

High-level category of purchase objective. Determines how the system interprets specification and downstream workflows. Values: product (physical or digital goods), service (flights, hotels, reservations), composite (multi-part purchase such as a trip).

Available options:
product,
service,
composite
autonomy_level
enum<string>
default:approve_before_purchase

How much authority the agent has to act without additional user approval. conditions are only used when autonomy_level is auto_within_conditions. Values: supervised (requires approval before each meaningful step), approve_before_purchase (can search and prepare autonomously, requires approval before purchase), auto_within_conditions (may auto-execute only when all configured conditions are met), autonomous (may execute without explicit approval, still bounded by constraints).

Available options:
supervised,
approve_before_purchase,
auto_within_conditions,
autonomous
constraints
IPAConstraint · object

Selection constraints for acceptable results. Not auto-execution triggers. Structured requirements and preferences that define what outcomes are acceptable. Used during parsing, search, validation, and manifest construction. Think of these as selection filters and guardrails. Examples: maximum total price, preferred brands, excluded brands, allowed item condition (new, refurbished, used), delivery window, quantity.

conditions
(PriceTargetCondition · object | BudgetCapCondition · object | AvailabilityCondition · object | TimeWindowCondition · object | FlightRouteCondition · object | CoverageMinimumCondition · object | JurisdictionCondition · object | ConditionGroup · object)[] | null

Execution triggers for monitoring / auto-execution. Not search constraints. Structured auto-execution triggers evaluated after approval or during monitoring. Used only to decide when an already-approved IPA may proceed automatically. Think of these as execution triggers, not search filters. Examples: buy when total falls below 180 GBP, execute if price drops by 10%, execute when item becomes available, execute within a specified time window.

Auto-execute when the lowest offer price satisfies a comparison against a target.

originating_agent_task_id
string | null

External ID of an existing agent task to link this IPA to (e.g., 'task-abc123'). When provided, the IPA is attached to this agent task instead of creating a new one. Mutually exclusive with the Idempotency-Key header.

originating_chat_id
string | null

External ID of the chat session this IPA originated from. Used for traceability when IPAs are created via the chat agent.

pint_uri
string | null

URI of a PINT (Payment Intent Token) to link to this IPA for spending limit enforcement. When provided, the PINT is validated (exists, belongs to user, not revoked/expired) and linked to the agent task before the preflight workflow triggers.

Minimum string length: 1

Response

IPA created, pre-flight workflow triggered

HAL-style hypermedia links for navigation and available actions.

intent
IPAData · object
required