Product fit API

Problem

Shopping agents need source-grounded signals for price, must-have terms, avoid terms, compatibility, shipping, and availability. Product pages can be incomplete, blocked, or mostly navigation, so agents need conservative fit signals and confidence instead of unsupported claims.

Relevant Primitive402 tool

Fetches a public product page and returns conservative product-fit signals for budget, must-have terms, avoid terms, compatibility, use case, shipping, and availability constraints.

curl example

curl -s https://primitive402.dev/v1/check-product-fit \
  -H 'content-type: application/json' \
  -d '{
  "productUrl": "https://example.com/products/daypack",
  "constraints": {
    "budgetMax": 120,
    "currency": "USD",
    "mustHave": [
      "water resistant",
      "laptop sleeve"
    ],
    "avoid": [
      "final sale"
    ],
    "compatibleWith": [
      "15 inch laptop"
    ],
    "useCase": "commuting",
    "locationOrShipping": "ships to United States"
  },
  "strictness": "medium",
  "maxSnippets": 5
}' | jq

TypeScript SDK example

import { createPrimitive402Client } from "@primitive402/sdk";

const client = createPrimitive402Client({
  baseUrl: "https://primitive402.dev"
});

const result = await client.checkProductFit({
  "productUrl": "https://example.com/products/daypack",
  "constraints": {
    "budgetMax": 120,
    "currency": "USD",
    "mustHave": [
      "water resistant",
      "laptop sleeve"
    ],
    "avoid": [
      "final sale"
    ],
    "compatibleWith": [
      "15 inch laptop"
    ],
    "useCase": "commuting",
    "locationOrShipping": "ships to United States"
  },
  "strictness": "medium",
  "maxSnippets": 5
});
console.log(result);

Example JSON response

{
  "fit_score": 82,
  "verdict": "good_fit",
  "matched_constraints": [
    "budgetMax: detected $89 within 120",
    "mustHave: water resistant",
    "compatibleWith: 15 inch laptop"
  ],
  "unmet_constraints": [],
  "concerns": [],
  "price_detected": "$89",
  "compatibility_notes": [
    "Page text appears to mention compatibility with 15 inch laptop."
  ],
  "shipping_or_availability_notes": [
    "In stock with free shipping."
  ],
  "extracted_snippets": [
    "Price $89. Water resistant daypack with laptop sleeve."
  ],
  "confidence": 0.76,
  "content_hash": "sha256:...",
  "source_url": "https://example.com/products/daypack"
}

Useful search terms

product fit API, shopping agent API, buyer constraint check, product compatibility API, commerce agent product evaluation

Example source note

Primitive402 only reports signals supported by fetched public page text. Price detection is conservative: service fees, repair or replacement fees, add-ons, monthly/installment/payment-plan amounts, shipping, tax, or subscription amounts are not treated as full product prices, so price_detected may remain null when only non-product prices are available. Avoid terms are evaluated with nearby context where possible: unrelated service promos, free-trial offers, and low-relevance sitewide mentions may become soft concerns, while product-relevant requirements still count as unmet constraints. Rendered/browser price extraction may be considered later as an explicit higher-cost mode; the default check_product_fit remains static and conservative for safety, cost, and reproducibility.

Related docs