Create, inspect, and drive an Errand through its lifecycle using the Platform API.
An is the durable contract between a user and an agent — what the user wants, what the agent may do, and under which signed authorisations. This guide covers the Platform API surface: request and response shape, lifecycle actions, and how to expand related resources. On the wire, an Errand is created and driven through the IPA (Intelligent Purchase Authorisation) routes and lifecycle. For the concept and composition model, see Errands; for the state machine, see Errand lifecycle.
An Errand sits above its mandates. The Errand handles orchestration (finding, validating, approving); a with sr:us:pint:spend:execute authorises the on-chain transaction at execution time. See scopes.
A verified user with a deployed Safe — see onboarding.
A signed Stamped Mandate that carries the scopes the Errand needs (at minimum sr:us:pint:perpetual:search; add sr:us:pint:spend:execute to authorise execution). See Stamped Mandates for the mint flow and scopes for the catalog.
On the wire, you create an Errand with POST /v0/user/ipa, which returns 202 Accepted once the pre-flight workflow is triggered. Pass Idempotency-Key to guard against duplicate submissions: if a previous request with the same key successfully produced an Errand, the retry returns that original Errand with 208 Already Reported. If the previous attempt did not produce an Errand (e.g. it failed before creation), the retry is processed as a new request.
curl -X POST https://api.sumvin.com/v0/user/ipa \ -H "x-juno-jwt: <token>" \ -H "x-juno-orgid: <your-org-id>" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: ipa-req-0001" \ -d '{ "raw_intent": "Find me a pair of Nike Air Max 90 in size 10, under $150", "intent_type": "product", "autonomy_level": "approve_before_purchase", "constraints": { "max_price": 150.00, "currency": "USD" }, "originating_chat_id": "chat_xyz789", "pint_uri": "sr:us:pint:def456" }'
Selection filters (what results are acceptable). See constraints.
conditions
array
No
Auto-execution triggers. Only evaluated when autonomy_level = auto_within_conditions.
originating_chat_id
string
No
External ID of the chat session this Errand came from — carried through for traceability.
originating_agent_task_id
string
No
External ID of an existing agent task to attach this Errand to. Mutually exclusive with Idempotency-Key.
pint_uri
string
No
URI of a Stamped Mandate (PINT) to link to this Errand for spending-limit enforcement. Validated before pre-flight fires.
constraints answer what is acceptable (e.g. max_price = 200). conditions answer when an approved Errand may auto-execute (e.g. buy if price drops below 180). They are evaluated at different stages — don’t conflate them.
GET /v0/user/ipa/{ipa_id}/events returns every state change, clarification exchange, approval decision, workflow transition, and cancellation recorded against the Errand. Fetch it directly, or embed it via expand=events on the detail endpoint.
Structured requirements that define what results the agent may propose. Evaluated during parsing, search, validation, and manifest construction — not during execution monitoring.
Auto-execution triggers evaluated once an Errand is approved with autonomy_level = auto_within_conditions. Each condition is typed by type (price_target, budget_cap, availability, time_window, flight_route, coverage_minimum, jurisdiction, group). See the Create Errand reference for the per-type schemas.
Idempotency-Key on POST /v0/user/ipa deduplicates retries when a prior request with the same key already produced an Errand — that original is returned with 208 Already Reported. Retries of a failed prior attempt are processed as new requests. Mutually exclusive with originating_agent_task_id in the body.
Every response carries _links — the presence of a link is the authoritative signal that the action is valid. See HAL, RFC 7807, idempotency, pagination.
