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"
    }
  ]
}

curl --request POST \
  --url https://api.sumvin.com/v0/user/ipa/ \
  --header 'Content-Type: application/json' \
  --header 'x-juno-jwt: <api-key>' \
  --data '
{
  "raw_intent": "<string>",
  "intent_type": "product",
  "autonomy_level": "approve_before_purchase",
  "constraints": {
    "max_price": 123,
    "max_total": 123,
    "currency": "<string>",
    "deadline": 123,
    "preferred_sellers": [
      "<string>"
    ],
    "excluded_sellers": [
      "<string>"
    ],
    "extra": {}
  },
  "conditions": [
    {
      "type": "<string>",
      "target_price": 123,
      "currency": "USD"
    }
  ],
  "originating_agent_task_id": "<string>",
  "originating_chat_id": "<string>"
}
'

import requests

url = "https://api.sumvin.com/v0/user/ipa/"

payload = {
    "raw_intent": "<string>",
    "intent_type": "product",
    "autonomy_level": "approve_before_purchase",
    "constraints": {
        "max_price": 123,
        "max_total": 123,
        "currency": "<string>",
        "deadline": 123,
        "preferred_sellers": ["<string>"],
        "excluded_sellers": ["<string>"],
        "extra": {}
    },
    "conditions": [
        {
            "type": "<string>",
            "target_price": 123,
            "currency": "USD"
        }
    ],
    "originating_agent_task_id": "<string>",
    "originating_chat_id": "<string>"
}
headers = {
    "x-juno-jwt": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-juno-jwt': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    raw_intent: '<string>',
    intent_type: 'product',
    autonomy_level: 'approve_before_purchase',
    constraints: {
      max_price: 123,
      max_total: 123,
      currency: '<string>',
      deadline: 123,
      preferred_sellers: ['<string>'],
      excluded_sellers: ['<string>'],
      extra: {}
    },
    conditions: [{type: '<string>', target_price: 123, currency: 'USD'}],
    originating_agent_task_id: '<string>',
    originating_chat_id: '<string>'
  })
};

fetch('https://api.sumvin.com/v0/user/ipa/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sumvin.com/v0/user/ipa/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'raw_intent' => '<string>',
    'intent_type' => 'product',
    'autonomy_level' => 'approve_before_purchase',
    'constraints' => [
        'max_price' => 123,
        'max_total' => 123,
        'currency' => '<string>',
        'deadline' => 123,
        'preferred_sellers' => [
                '<string>'
        ],
        'excluded_sellers' => [
                '<string>'
        ],
        'extra' => [
                
        ]
    ],
    'conditions' => [
        [
                'type' => '<string>',
                'target_price' => 123,
                'currency' => 'USD'
        ]
    ],
    'originating_agent_task_id' => '<string>',
    'originating_chat_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-juno-jwt: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sumvin.com/v0/user/ipa/"

	payload := strings.NewReader("{\n  \"raw_intent\": \"<string>\",\n  \"intent_type\": \"product\",\n  \"autonomy_level\": \"approve_before_purchase\",\n  \"constraints\": {\n    \"max_price\": 123,\n    \"max_total\": 123,\n    \"currency\": \"<string>\",\n    \"deadline\": 123,\n    \"preferred_sellers\": [\n      \"<string>\"\n    ],\n    \"excluded_sellers\": [\n      \"<string>\"\n    ],\n    \"extra\": {}\n  },\n  \"conditions\": [\n    {\n      \"type\": \"<string>\",\n      \"target_price\": 123,\n      \"currency\": \"USD\"\n    }\n  ],\n  \"originating_agent_task_id\": \"<string>\",\n  \"originating_chat_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-juno-jwt", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sumvin.com/v0/user/ipa/")
  .header("x-juno-jwt", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"raw_intent\": \"<string>\",\n  \"intent_type\": \"product\",\n  \"autonomy_level\": \"approve_before_purchase\",\n  \"constraints\": {\n    \"max_price\": 123,\n    \"max_total\": 123,\n    \"currency\": \"<string>\",\n    \"deadline\": 123,\n    \"preferred_sellers\": [\n      \"<string>\"\n    ],\n    \"excluded_sellers\": [\n      \"<string>\"\n    ],\n    \"extra\": {}\n  },\n  \"conditions\": [\n    {\n      \"type\": \"<string>\",\n      \"target_price\": 123,\n      \"currency\": \"USD\"\n    }\n  ],\n  \"originating_agent_task_id\": \"<string>\",\n  \"originating_chat_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sumvin.com/v0/user/ipa/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-juno-jwt"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"raw_intent\": \"<string>\",\n  \"intent_type\": \"product\",\n  \"autonomy_level\": \"approve_before_purchase\",\n  \"constraints\": {\n    \"max_price\": 123,\n    \"max_total\": 123,\n    \"currency\": \"<string>\",\n    \"deadline\": 123,\n    \"preferred_sellers\": [\n      \"<string>\"\n    ],\n    \"excluded_sellers\": [\n      \"<string>\"\n    ],\n    \"extra\": {}\n  },\n  \"conditions\": [\n    {\n      \"type\": \"<string>\",\n      \"target_price\": 123,\n      \"currency\": \"USD\"\n    }\n  ],\n  \"originating_agent_task_id\": \"<string>\",\n  \"originating_chat_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "_links": {},
  "intent": {
    "id": "<string>",
    "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": {}
    },
    "conditions": [
      {
        "type": "<string>",
        "target_price": "<string>",
        "currency": "USD"
      }
    ],
    "monitor_until": 123,
    "clarification_questions": [
      "<string>"
    ],
    "failure_reason": "<string>",
    "pint_uris": [
      "<string>"
    ],
    "updated_at": 123,
    "completed_at": 123,
    "capacity": {
      "consumed": "<string>",
      "reserved": "<string>",
      "enforcement_mode": "<string>",
      "mandate_pint_uri": "<string>",
      "max_amount": "<string>",
      "remaining": "<string>",
      "asset": "<string>"
    },
    "manifest_summary": {
      "id": "<string>",
      "status": "<string>",
      "item_count": 123,
      "total_amount": "<string>",
      "total_asset": "<string>",
      "approved_at": 123,
      "purchased_at": 123
    },
    "preflight_workflow_id": "<string>",
    "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>",
        "created_at": 123,
        "payload": {}
      }
    ],
    "approval_payload": {
      "types": {},
      "primaryType": "<string>",
      "domain": {
        "name": "<string>",
        "version": "<string>",
        "chainId": 123,
        "verifyingContract": "<string>"
      },
      "message": {
        "wallet": "<string>",
        "nonce": 123,
        "statement": "<string>",
        "scopes": [
          "<string>"
        ],
        "resources": [
          "<string>"
        ],
        "maxAmount": 123,
        "maxAmountToken": "<string>",
        "expiresAt": 123,
        "conditions": [
          "<string>"
        ]
      }
    }
  }
}

{
  "_links": {},
  "intent": {
    "id": "<string>",
    "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": {}
    },
    "conditions": [
      {
        "type": "<string>",
        "target_price": "<string>",
        "currency": "USD"
      }
    ],
    "monitor_until": 123,
    "clarification_questions": [
      "<string>"
    ],
    "failure_reason": "<string>",
    "pint_uris": [
      "<string>"
    ],
    "updated_at": 123,
    "completed_at": 123,
    "capacity": {
      "consumed": "<string>",
      "reserved": "<string>",
      "enforcement_mode": "<string>",
      "mandate_pint_uri": "<string>",
      "max_amount": "<string>",
      "remaining": "<string>",
      "asset": "<string>"
    },
    "manifest_summary": {
      "id": "<string>",
      "status": "<string>",
      "item_count": 123,
      "total_amount": "<string>",
      "total_asset": "<string>",
      "approved_at": 123,
      "purchased_at": 123
    },
    "preflight_workflow_id": "<string>",
    "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>",
        "created_at": 123,
        "payload": {}
      }
    ],
    "approval_payload": {
      "types": {},
      "primaryType": "<string>",
      "domain": {
        "name": "<string>",
        "version": "<string>",
        "chainId": 123,
        "verifyingContract": "<string>"
      },
      "message": {
        "wallet": "<string>",
        "nonce": 123,
        "statement": "<string>",
        "scopes": [
          "<string>"
        ],
        "resources": [
          "<string>"
        ],
        "maxAmount": 123,
        "maxAmountToken": "<string>",
        "expiresAt": 123,
        "conditions": [
          "<string>"
        ]
      }
    }
  }
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

IPA

Create IPA

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 vs conditions

	`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.

POST

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"
    }
  ]
}

curl --request POST \
  --url https://api.sumvin.com/v0/user/ipa/ \
  --header 'Content-Type: application/json' \
  --header 'x-juno-jwt: <api-key>' \
  --data '
{
  "raw_intent": "<string>",
  "intent_type": "product",
  "autonomy_level": "approve_before_purchase",
  "constraints": {
    "max_price": 123,
    "max_total": 123,
    "currency": "<string>",
    "deadline": 123,
    "preferred_sellers": [
      "<string>"
    ],
    "excluded_sellers": [
      "<string>"
    ],
    "extra": {}
  },
  "conditions": [
    {
      "type": "<string>",
      "target_price": 123,
      "currency": "USD"
    }
  ],
  "originating_agent_task_id": "<string>",
  "originating_chat_id": "<string>"
}
'

import requests

url = "https://api.sumvin.com/v0/user/ipa/"

payload = {
    "raw_intent": "<string>",
    "intent_type": "product",
    "autonomy_level": "approve_before_purchase",
    "constraints": {
        "max_price": 123,
        "max_total": 123,
        "currency": "<string>",
        "deadline": 123,
        "preferred_sellers": ["<string>"],
        "excluded_sellers": ["<string>"],
        "extra": {}
    },
    "conditions": [
        {
            "type": "<string>",
            "target_price": 123,
            "currency": "USD"
        }
    ],
    "originating_agent_task_id": "<string>",
    "originating_chat_id": "<string>"
}
headers = {
    "x-juno-jwt": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-juno-jwt': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    raw_intent: '<string>',
    intent_type: 'product',
    autonomy_level: 'approve_before_purchase',
    constraints: {
      max_price: 123,
      max_total: 123,
      currency: '<string>',
      deadline: 123,
      preferred_sellers: ['<string>'],
      excluded_sellers: ['<string>'],
      extra: {}
    },
    conditions: [{type: '<string>', target_price: 123, currency: 'USD'}],
    originating_agent_task_id: '<string>',
    originating_chat_id: '<string>'
  })
};

fetch('https://api.sumvin.com/v0/user/ipa/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sumvin.com/v0/user/ipa/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'raw_intent' => '<string>',
    'intent_type' => 'product',
    'autonomy_level' => 'approve_before_purchase',
    'constraints' => [
        'max_price' => 123,
        'max_total' => 123,
        'currency' => '<string>',
        'deadline' => 123,
        'preferred_sellers' => [
                '<string>'
        ],
        'excluded_sellers' => [
                '<string>'
        ],
        'extra' => [
                
        ]
    ],
    'conditions' => [
        [
                'type' => '<string>',
                'target_price' => 123,
                'currency' => 'USD'
        ]
    ],
    'originating_agent_task_id' => '<string>',
    'originating_chat_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-juno-jwt: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sumvin.com/v0/user/ipa/"

	payload := strings.NewReader("{\n  \"raw_intent\": \"<string>\",\n  \"intent_type\": \"product\",\n  \"autonomy_level\": \"approve_before_purchase\",\n  \"constraints\": {\n    \"max_price\": 123,\n    \"max_total\": 123,\n    \"currency\": \"<string>\",\n    \"deadline\": 123,\n    \"preferred_sellers\": [\n      \"<string>\"\n    ],\n    \"excluded_sellers\": [\n      \"<string>\"\n    ],\n    \"extra\": {}\n  },\n  \"conditions\": [\n    {\n      \"type\": \"<string>\",\n      \"target_price\": 123,\n      \"currency\": \"USD\"\n    }\n  ],\n  \"originating_agent_task_id\": \"<string>\",\n  \"originating_chat_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-juno-jwt", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sumvin.com/v0/user/ipa/")
  .header("x-juno-jwt", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"raw_intent\": \"<string>\",\n  \"intent_type\": \"product\",\n  \"autonomy_level\": \"approve_before_purchase\",\n  \"constraints\": {\n    \"max_price\": 123,\n    \"max_total\": 123,\n    \"currency\": \"<string>\",\n    \"deadline\": 123,\n    \"preferred_sellers\": [\n      \"<string>\"\n    ],\n    \"excluded_sellers\": [\n      \"<string>\"\n    ],\n    \"extra\": {}\n  },\n  \"conditions\": [\n    {\n      \"type\": \"<string>\",\n      \"target_price\": 123,\n      \"currency\": \"USD\"\n    }\n  ],\n  \"originating_agent_task_id\": \"<string>\",\n  \"originating_chat_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sumvin.com/v0/user/ipa/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-juno-jwt"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"raw_intent\": \"<string>\",\n  \"intent_type\": \"product\",\n  \"autonomy_level\": \"approve_before_purchase\",\n  \"constraints\": {\n    \"max_price\": 123,\n    \"max_total\": 123,\n    \"currency\": \"<string>\",\n    \"deadline\": 123,\n    \"preferred_sellers\": [\n      \"<string>\"\n    ],\n    \"excluded_sellers\": [\n      \"<string>\"\n    ],\n    \"extra\": {}\n  },\n  \"conditions\": [\n    {\n      \"type\": \"<string>\",\n      \"target_price\": 123,\n      \"currency\": \"USD\"\n    }\n  ],\n  \"originating_agent_task_id\": \"<string>\",\n  \"originating_chat_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "_links": {},
  "intent": {
    "id": "<string>",
    "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": {}
    },
    "conditions": [
      {
        "type": "<string>",
        "target_price": "<string>",
        "currency": "USD"
      }
    ],
    "monitor_until": 123,
    "clarification_questions": [
      "<string>"
    ],
    "failure_reason": "<string>",
    "pint_uris": [
      "<string>"
    ],
    "updated_at": 123,
    "completed_at": 123,
    "capacity": {
      "consumed": "<string>",
      "reserved": "<string>",
      "enforcement_mode": "<string>",
      "mandate_pint_uri": "<string>",
      "max_amount": "<string>",
      "remaining": "<string>",
      "asset": "<string>"
    },
    "manifest_summary": {
      "id": "<string>",
      "status": "<string>",
      "item_count": 123,
      "total_amount": "<string>",
      "total_asset": "<string>",
      "approved_at": 123,
      "purchased_at": 123
    },
    "preflight_workflow_id": "<string>",
    "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>",
        "created_at": 123,
        "payload": {}
      }
    ],
    "approval_payload": {
      "types": {},
      "primaryType": "<string>",
      "domain": {
        "name": "<string>",
        "version": "<string>",
        "chainId": 123,
        "verifyingContract": "<string>"
      },
      "message": {
        "wallet": "<string>",
        "nonce": 123,
        "statement": "<string>",
        "scopes": [
          "<string>"
        ],
        "resources": [
          "<string>"
        ],
        "maxAmount": 123,
        "maxAmountToken": "<string>",
        "expiresAt": 123,
        "conditions": [
          "<string>"
        ]
      }
    }
  }
}

{
  "_links": {},
  "intent": {
    "id": "<string>",
    "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": {}
    },
    "conditions": [
      {
        "type": "<string>",
        "target_price": "<string>",
        "currency": "USD"
      }
    ],
    "monitor_until": 123,
    "clarification_questions": [
      "<string>"
    ],
    "failure_reason": "<string>",
    "pint_uris": [
      "<string>"
    ],
    "updated_at": 123,
    "completed_at": 123,
    "capacity": {
      "consumed": "<string>",
      "reserved": "<string>",
      "enforcement_mode": "<string>",
      "mandate_pint_uri": "<string>",
      "max_amount": "<string>",
      "remaining": "<string>",
      "asset": "<string>"
    },
    "manifest_summary": {
      "id": "<string>",
      "status": "<string>",
      "item_count": 123,
      "total_amount": "<string>",
      "total_asset": "<string>",
      "approved_at": 123,
      "purchased_at": 123
    },
    "preflight_workflow_id": "<string>",
    "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>",
        "created_at": 123,
        "payload": {}
      }
    ],
    "approval_payload": {
      "types": {},
      "primaryType": "<string>",
      "domain": {
        "name": "<string>",
        "version": "<string>",
        "chainId": 123,
        "verifyingContract": "<string>"
      },
      "message": {
        "wallet": "<string>",
        "nonce": 123,
        "statement": "<string>",
        "scopes": [
          "<string>"
        ],
        "resources": [
          "<string>"
        ],
        "maxAmount": 123,
        "maxAmountToken": "<string>",
        "expiresAt": 123,
        "conditions": [
          "<string>"
        ]
      }
    }
  }
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

Authorizations

x-juno-jwt

string

header

required

JWT issued by Dynamic Labs or Privy. Sent in the x-juno-jwt header on every authenticated request.

Headers

Idempotency-Key

string | null

x-juno-orgid

string | null

Tenant org ID for multi-tenant auth

x-sumvin-token

string | null

x-sumvin-pat

string | null

x-juno-jwt

string | null

X-Timestamp-Format

string

Controls how timestamp fields are serialized in JSON response bodies.

Default (header omitted or any other value): epoch milliseconds as integers. iso8601: UTC ISO 8601 strings of the form YYYY-MM-DDTHH:MM:SSZ.

Example: with X-Timestamp-Format: iso8601, the field value 1704067200000 becomes "2024-01-01T00:00:00Z".

Affected fields (recursively, in dicts and arrays): any field whose name ends in _at, plus the literal field names timestamp, period_start, and period_end. All other fields are passed through unchanged.

Only iso8601 is recognized. Any other value (or omitting the header) yields the default epoch-ms representation; the server does not reject unknown values, so this is documented as an example rather than an enum to keep generated clients permissive.

Example:

"iso8601"

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 | null

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.

Show child attributes

conditions

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.

Show child attributes

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.

Response

IPA created, pre-flight workflow triggered

_links

Links · object

required

HAL-style hypermedia links for navigation and available actions.

Show child attributes

intent

IPAData · object

required

Show child attributes

⌘I

Introduction

Quickstarts

Guides

Product Guides

API Reference

Create IPA

constraints vs conditions

Authorizations

Headers

Body

Response