recommend: skill contract

recommend returns up to 128 catalog products, either related to a seed_sku or matching a free-text query. Products use the same shape as browse_catalog; there is no cursor. It returns public catalog data, so no customer email is sent.

When neither seed_sku nor query is present, return { "products": [] }.

Request

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

Field	Type	Required	Notes
seed_sku	string	no	Recommend products related to this SKU. 1–128 chars.
query	string	no	Free text to match, used when there is no seed SKU. 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 a browse_catalog product: sku, title, price and availability are required, the rest optional, and no other fields are allowed.

{
  "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

A response that does not match the schema is not passed to the agent and counts as a failed call; 3 failures in a row mark the skill UNREACHABLE. Common causes are an extra field at any depth and a product missing sku, title, price or availability.

Verify the signature

Check the X-Sill-Signature header on every request before answering. The scheme is the same for every skill; see Verify the signature for tested TypeScript, Python and Go code.

See also

• Contract overview — request envelope, response handling and signature code.
• browse_catalog — shares the product shape.