Creates a new Intelligent Purchase Authorization from a natural-language 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.
constraints | conditions | |
|---|---|---|
| Purpose | What acceptable options must satisfy | When an approved intent may auto-execute |
| Used during | Parsing, search, validation, manifest construction | Monitoring, post-approval evaluation |
| Example | max_price = 200 — results above 200 are not proposed | target_price = 180 — auto-execute if price drops below 180 |
conditions are only evaluated when autonomy_level is auto_within_conditions.
Tenant org ID for multi-tenant auth
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 user request in natural language. Preserved exactly as submitted for auditability and re-parsing.
1 - 2000"Buy AirPods Pro under £180 and wait up to 2 weeks."
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).
product, service, composite 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).
supervised, approve_before_purchase, auto_within_conditions, autonomous 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.
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.
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.
External ID of the chat session this IPA originated from. Used for traceability when IPAs are created via the chat agent.
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.
1