recommend

recommend returns a bounded array of catalog products, either related to a seed_sku or matching a free-text query. The response is structurally identical to browse_catalog’s products[] — no cursor.

recommend is NOT customer-scoped. It returns public catalog data. Sill does not send customer_email and your handler should not scope the response to any customer.

At least one of seed_sku or query should be provided. When both are absent, respond with an empty products array.

Request

Machine-readable: /skills/v1/recommend.request.schema.json

Field	Type	Required	Notes
seed_sku	string	no	A SKU to recommend “related to”. 1–128 chars.
query	string	no	A free-text query when no seed SKU is available. 1–256 chars.
limit	integer	no	Page size. 1–50.

{
  "additionalProperties": false,
  "properties": {
    "limit": {
      "maximum": 50,
      "minimum": 1,
      "type": "integer"
    },
    "query": {
      "maxLength": 256,
      "minLength": 1,
      "type": "string"
    },
    "seed_sku": {
      "maxLength": 128,
      "minLength": 1,
      "type": "string"
    }
  },
  "type": "object"
}

Example request — related to a seed

{
  "skill_id": "recommend",
  "site_id": "01EXAMPLE00000000000000000",
  "arguments": {
    "seed_sku": "beans_medium_12oz",
    "limit": 5
  },
  "observed_at": "2026-07-05T18:22:15.140Z",
  "nonce": "01K1EXAMPLE0000000000000000"
}

Example request — free-text

{
  "skill_id": "recommend",
  "site_id": "01EXAMPLE00000000000000000",
  "arguments": {
    "query": "beginner pour-over setup",
    "limit": 5
  },
  "observed_at": "2026-07-05T18:22:15.140Z",
  "nonce": "01K1EXAMPLE0000000000000000"
}

Response

Machine-readable: /skills/v1/recommend.response.schema.json

Field	Type	Required	Notes
products	array	yes	Up to 128 recommended products.

Each product has the SAME shape as browse_catalog’s product — sku, title, price, availability required, everything else optional. additionalProperties: false at every depth.

{
  "additionalProperties": false,
  "properties": {
    "products": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "availability": {
            "enum": ["in_stock", "low_stock", "out_of_stock", "unknown"],
            "type": "string"
          },
          "brand": { "maxLength": 256, "minLength": 1, "type": "string" },
          "description": { "maxLength": 2048, "minLength": 1, "type": "string" },
          "has_more_variants": { "type": "boolean" },
          "image_url": { "maxLength": 2048, "minLength": 1, "type": "string" },
          "options": {
            "items": {
              "additionalProperties": false,
              "properties": {
                "name": { "maxLength": 128, "minLength": 1, "type": "string" },
                "values": {
                  "items": { "maxLength": 256, "minLength": 1, "type": "string" },
                  "maxItems": 64,
                  "type": "array"
                }
              },
              "required": ["name", "values"],
              "type": "object"
            },
            "maxItems": 32,
            "type": "array"
          },
          "price": {
            "additionalProperties": false,
            "properties": {
              "amount": { "type": "number" },
              "amount_decimal": { "maxLength": 64, "minLength": 1, "type": "string" },
              "currency": { "maxLength": 8, "minLength": 3, "type": "string" }
            },
            "required": ["amount", "amount_decimal", "currency"],
            "type": "object"
          },
          "sku": { "maxLength": 256, "minLength": 1, "type": "string" },
          "title": { "maxLength": 512, "minLength": 1, "type": "string" },
          "url": { "maxLength": 2048, "minLength": 1, "type": "string" },
          "variants": {
            "items": {
              "additionalProperties": false,
              "properties": {
                "availability": {
                  "enum": ["in_stock", "low_stock", "out_of_stock", "unknown"],
                  "type": "string"
                },
                "options": {
                  "items": {
                    "additionalProperties": false,
                    "properties": {
                      "name": { "maxLength": 128, "minLength": 1, "type": "string" },
                      "value": { "maxLength": 256, "minLength": 1, "type": "string" }
                    },
                    "required": ["name", "value"],
                    "type": "object"
                  },
                  "maxItems": 32,
                  "type": "array"
                },
                "price": {
                  "additionalProperties": false,
                  "properties": {
                    "amount": { "type": "number" },
                    "amount_decimal": { "maxLength": 64, "minLength": 1, "type": "string" },
                    "currency": { "maxLength": 8, "minLength": 3, "type": "string" }
                  },
                  "required": ["amount", "amount_decimal", "currency"],
                  "type": "object"
                },
                "sku": { "maxLength": 256, "minLength": 1, "type": "string" },
                "title": { "maxLength": 512, "minLength": 1, "type": "string" }
              },
              "required": ["sku", "title", "price", "availability"],
              "type": "object"
            },
            "maxItems": 64,
            "type": "array"
          }
        },
        "required": ["sku", "title", "price", "availability"],
        "type": "object"
      },
      "maxItems": 128,
      "type": "array"
    }
  },
  "required": ["products"],
  "type": "object"
}

Example response

{
  "products": [
    {
      "sku": "beans_dark_12oz",
      "title": "Dark roast, 12 oz bag",
      "price": {
        "amount": 1800,
        "amount_decimal": "18.00",
        "currency": "USD"
      },
      "availability": "in_stock",
      "url": "https://example.com/products/beans-dark-12oz"
    },
    {
      "sku": "filter_v60_02",
      "title": "V60 filter, 100 pack",
      "price": {
        "amount": 900,
        "amount_decimal": "9.00",
        "currency": "USD"
      },
      "availability": "in_stock",
      "url": "https://example.com/products/filter-v60-02"
    }
  ]
}

What Sill checks

• Extra fields are rejected at every depth.
• Every product needs sku, title, price, availability. A partial product is rejected.

Verifying Sill’s signature

Every request Sill POSTs to your endpoint carries a X-Sill-Signature: t=<unix>,v1=<hex> header, where <hex> is HMAC-SHA256("<t>.<raw-body>") with your shared secret.

TypeScript (compact)

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(header: string, body: string, secret: string): boolean {
  const map = Object.fromEntries(header.split(',').map((p) => p.split('=', 2)));
  const t = Number(map.t);
  const sig = String(map.v1 ?? '');
  if (!Number.isFinite(t) || sig.length === 0) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${body}`).digest();
  const got = Buffer.from(sig, 'hex');
  if (expected.length !== got.length) return false;
  return timingSafeEqual(expected, got);
}

Python (compact)

import hmac, hashlib, time

def verify(header: str, body: bytes, secret: bytes) -> bool:
    parts = dict(p.split('=', 1) for p in header.split(',') if '=' in p)
    try:
        t = int(parts['t'])
    except (KeyError, ValueError):
        return False
    sig = parts.get('v1', '')
    if abs(int(time.time()) - t) > 300 or not sig:
        return False
    expected = hmac.new(secret, f'{t}.'.encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

Go (compact)

func Verify(header string, body []byte, secret []byte) bool {
    var t int64 = -1
    var sig string
    for _, p := range strings.Split(header, ",") {
        kv := strings.SplitN(p, "=", 2)
        if len(kv) != 2 { continue }
        switch kv[0] {
        case "t":
            n, err := strconv.ParseInt(kv[1], 10, 64)
            if err != nil { return false }
            t = n
        case "v1":
            sig = kv[1]
        }
    }
    if t < 0 || sig == "" { return false }
    diff := time.Now().Unix() - t
    if diff < 0 { diff = -diff }
    if diff > 300 { return false }
    mac := hmac.New(sha256.New, secret)
    mac.Write([]byte(strconv.FormatInt(t, 10) + "."))
    mac.Write(body)
    got, err := hex.DecodeString(sig)
    if err != nil { return false }
    return hmac.Equal(mac.Sum(nil), got)
}

See also

• Contract overview — envelope shape, versioning, and the full HMAC verification samples.
• browse_catalog — shares the product shape.