Connect a feed. Send the moment. Get the match.

Two endpoints. Connect your catalogue once with /v1/feed, then post a brief, a content signal or a shopping ask to /v1/match. The same engine powers Plan, Discover and Ask.

Get a sandbox key

10 calls / minute · no card

Generate a sandbox key and start hitting /v1/match in the next minute. Sandbox keys are capped at 10 calls per minute — plenty to feel the engine. Book a demo to lift the cap and connect your real catalogue.

Book a demo

01Connect your catalogue

Point Contux at your product feed and set the rules that govern where products can appear. You only do this once per catalogue. Contux builds the context map — occasions, style language, pairings and negative contexts — on top of your existing feed fields.

POST /v1/feed

curl https://api.contux.dev/v1/feed \
  -H "Authorization: Bearer ck_sandbox_..." \
  -H "Content-Type: application/json" \
  -d '{
    "source": "shopify_catalogue",
    "store": "menswear-store.myshopify.com",
    "map": ["occasions", "style", "constraints", "pairings"],
    "rules": {
      "in_stock_only": true,
      "allowed_surfaces": ["plan", "discover", "ask"],
      "blocked_contexts": ["tragedy", "adult"]
    }
  }'

02Send context, get matches

Post the moment to /v1/match. The surface field tells Contux which entry point you’re using; the contextis the brief, the content (or its URL), or the shopper’s raw words. You get back ranked, approved matches with reasons and satisfied rules.

POST /v1/match

curl https://api.contux.dev/v1/match \
  -H "Authorization: Bearer ck_sandbox_..." \
  -H "Content-Type: application/json" \
  -d '{
    "surface": "ask",
    "context_type": "shopper_prompt",
    "context": "winery wedding in Orange, 13°C, blue suit, orange tie, no black shoes, budget $700, before Friday",
    "feed_id": "menswear",
    "limit": 4
  }'

Every match comes back explainable:

200 OK

{
  "matches": [
    {
      "product_id": "tan_loafer_123",
      "score": 0.95,
      "availability": "in_stock",
      "rules_satisfied": ["not_black", "arrives_before_friday", "within_budget"],
      "matched_signals": ["winery wedding", "blue suit", "orange tie"],
      "reason": "Complements the blue-and-orange palette, avoids black shoes, and arrives in time."
    }
  ],
  "surface": "ask",
  "total_estimated": 626
}

03One body shape, three surfaces

The only thing that changes between Plan, Discover and Ask is the surface and the context. Same feed, same response shape.

Plan — a campaign brief

POST /v1/match

{
  "surface": "plan",
  "context_type": "campaign_brief",
  "context": "Launch Winter 2026 menswear. Premium but practical. Wool coats, leather boots, merino layers. Avoid discount-led environments.",
  "feed_id": "menswear"
}

Discover — a content signal

POST /v1/match

{
  "surface": "discover",
  "context_type": "content",
  "context": { "url": "https://weekendjournal.com/tasmania-winter-packing" },
  "feed_id": "menswear",
  "limit": 3
}

Ask — a shopper prompt

POST /v1/match

curl https://api.contux.dev/v1/match \
  -H "Authorization: Bearer ck_sandbox_..." \
  -H "Content-Type: application/json" \
  -d '{
    "surface": "ask",
    "context_type": "shopper_prompt",
    "context": "winery wedding in Orange, 13°C, blue suit, orange tie, no black shoes, budget $700, before Friday",
    "feed_id": "menswear",
    "limit": 4
  }'

04Rate limits & keys

Sandbox keys issued above are capped at 10 calls per minute so you can build and test without a card. Over the limit, the API returns 429 with a retry-after header. Production keys — with your real catalogue, higher limits and per-service keys — are set up during onboarding.

Tier	Rate limit	Catalogue
Sandbox	10 / min	Sample menswear feed
Production	By plan	Your live catalogue