Add Capabilities

POST /experiences/{experience_id}/capabilities

Add capabilities to an experience.

Creates sessions for each capability and queues background processing. Returns immediately with PENDING status while processing happens async.

Path parameters

experience_id string Required

application/json

Body Required

context object | null

User context shared across all capabilities.

Contains cart contents, purchase history, and other signals used for personalization.
Hide context attributes Show context attributes object | null
- cart object | null
  
  Container for product selections.
  
  Partners submit products they want to generate widgets for. Can include items from user's cart, browsing history, or curated selections.
  Hide cart attributes Show cart attributes object | null
  
  type string Required
  
  Values are grocery or fashion.
  
  products array[object] Required
  
  Product in a cart/selection.
  
  Two modes supported:
  
  Catalog reference (minimal): Only product_id required. Backend hydrates details.
  
  Inline (legacy): Full product details provided directly.
  
  For catalog-based products (e.g., fashion try-on), provide product_id. Product details are fetched from the catalog database. For inline products (e.g., grocery), provide name and details directly.
  
  Hide products attributes Show products attributes object
  
  productId string | null
  
  name string | null
  
  brand string | null
  
  price number | null
  
  category string | null
  
  quantity integer
  
  Default value is 1.
  
  size string | null
  
  unit string | null
  
  barcode string | null
  
  organic boolean | null
  
  Default value is false.
  
  glutenFree boolean | null
  
  Default value is false.
- trip object | null
  Hide trip attributes Show trip attributes object | null
  
  flight object | null
  
  Hide flight attributes Show flight attributes object | null
  
  departureAirport string Required
  
  arrivalAirport string Required
  
  departureTimestamp integer Required
  
  arrivalTimestamp integer Required
  
  numTravelers integer Required
  
  seatClass string Required
  
  Values are economy, main, premium, business, or first.
  
  cruise object | null
  
  Hide cruise attributes Show cruise attributes object | null
  
  departurePort string Required
  
  arrivalPort string Required
  
  departureTimestamp integer Required
  
  arrivalTimestamp integer Required
  
  numTravelers integer Required
- topic object | null
  Hide topic attributes Show topic attributes object | null
  
  topic string Required
  
  questions array[string] Required
- history object | null
  
  User's purchase/browsing history for personalization.
  Hide history attribute Show history attribute object | null
  
  orders array[object]
  
  A past order from purchase history.
  
  Two modes supported:
  
  Catalog reference (minimal): Only product_id required. Backend hydrates details.
  
  Inline (legacy): Full product details provided directly.
  
  Hide orders attributes Show orders attributes object
  
  productId string | null
  
  name string | null
  
  brand string | null
  
  category string | null
  
  color string | null
  
  purchasedAt string | null
capabilities array[object] Required

List of capabilities to add (at least one required)

At least 1 element.
One of:
catalog_recommendations object virtual_tryon object virtual_tryon_video object wardrobe_recommendations object research object recipes object nutrition_analysis object weekly_meal_plan object restaurants object wearables_tracking object
Request for catalog recommendations capability.
Hide attributes Show attributes

type string Required Discriminator

Value is catalog_recommendations.

config object Required

Configuration for catalog recommendations capability.

Hide config attributes Show config attributes object

allowedSources array[string]

blockedSources array[string]

catalogSlug string Required

maxResults integer

Minimum value is 1.0, maximum value is 12.0. Default value is 6.

budgetMax number | null
Request for virtual try-on capability.
Hide attributes Show attributes

type string Required Discriminator

Value is virtual_tryon.

config object Required

Configuration for virtual try-on capability.

Hide config attributes Show config attributes object

catalogSlug string Required

Catalog for product validation

resourceIds array[string] Required

S3 resource IDs: first is user photo, rest are wardrobe item images

At least 1 element.

selectedProductIds array[string]

Catalog product IDs to try on (optional if wardrobe items provided)
Request for virtual try-on video capability.
Hide attributes Show attributes

type string Required Discriminator

Value is virtual_tryon_video.

config object Required

Configuration for video generation from try-on image.

Generates a short video from a virtual try-on image using Veo 3.1. The video brings the static image to life, showing the user "wearing" the products in motion.

Hide config attributes Show config attributes object

sourceImageResourceId string Required

S3 resource ID of the generated try-on image

animationPrompt string | null

durationSeconds integer

Video duration: 4, 6, or 8 seconds

Minimum value is 4.0, maximum value is 8.0. Default value is 4.

aspectRatio string

Video aspect ratio: 16:9 or 9:16

Default value is 9:16.

resolution string

Video resolution: 720p or 1080p

Default value is 720p.
Request for wardrobe recommendations capability.
Hide attributes Show attributes

type string Required Discriminator

Value is wardrobe_recommendations.

config object Required

Configuration for wardrobe recommendations capability.

Analyzes a user's wardrobe (from purchase history) and recommends which accessory items complement the current outfit.

Hide config attributes Show config attributes object

allowedSources array[string]

blockedSources array[string]

catalogSlug string Required

wardrobeProductIds array[string] Required

Product IDs from user's purchase history to analyze

At least 1 but not more than 100 elements.

outfitProductIds array[string]

Product IDs representing current outfit (from cart/selection)

outfitContext string | null

maxResults integer

Minimum value is 1.0, maximum value is 30.0. Default value is 10.

minConfidence number

Minimum value is 0.0, maximum value is 1.0. Default value is 0.5.

styleFilter string | null

categoryFilter string | null
Request for research capability.
Hide attributes Show attributes

type string Required Discriminator

Value is research.

config object

Configuration for research capability.

Hide config attributes Show config attributes object

allowedSources array[string]

blockedSources array[string]

maxItems integer

Minimum value is 1.0, maximum value is 10.0. Default value is 5.
Request for recipes capability.
Hide attributes Show attributes

type string Required Discriminator

Value is recipes.

config object

Config for recipe generation.

Hide config attributes Show config attributes object

allowedSources array[string]

blockedSources array[string]

maxItems integer

Minimum value is 1.0, maximum value is 20.0. Default value is 5.
Request for nutrition analysis capability.
Hide attributes Show attributes

type string Required Discriminator

Value is nutrition_analysis.

config object

Config for nutrition analysis.

Hide config attributes Show config attributes object

allowedSources array[string]

blockedSources array[string]

maxItems integer

Minimum value is 1.0, maximum value is 20.0. Default value is 5.
Request for weekly meal plan capability.
Hide attributes Show attributes

type string Required Discriminator

Value is weekly_meal_plan.

config object

Config for weekly meal plan generation.

Hide config attributes Show config attributes object

allowedSources array[string]

blockedSources array[string]

days integer

Number of days to plan

Minimum value is 1.0, maximum value is 7.0. Default value is 7.
Request for trip-based recommendation capabilities.
Hide attributes Show attributes

type string Required Discriminator

Value is restaurants.

config object

Config for trip-based recommendation widgets.

Hide config attributes Show config attributes object

allowedSources array[string]

blockedSources array[string]

maxItems integer

Minimum value is 1.0, maximum value is 20.0. Default value is 5.
Request for cart-based recommendation capabilities.
Hide attributes Show attributes

type string Required Discriminator

Value is wearables_tracking.

config object

Config for cart-based recommendation widgets.

Hide config attributes Show config attributes object

allowedSources array[string]

blockedSources array[string]

maxItems integer

Minimum value is 1.0, maximum value is 20.0. Default value is 5.

Responses

200 application/json

Successful Response
Hide response attributes Show response attributes object
- experienceId string Required
- status string Required
- widgets array[object] Required
  
  One of:
  restaurants object wearables_tracking object catalog_recommendations object virtual_tryon object virtual_tryon_video object wardrobe_recommendations object recipes object nutrition_analysis object weekly_meal_plan object research object
  
  Hide attributes Show attributes
  
  capabilityId string Required
  
  status string Required
  
  currentVersion integer Required
  
  heading string | null
  
  errorMessage string | null
  
  type string Required Discriminator
  
  Value is restaurants.
  
  data object | null
  
  Widget data for trip and cart recommendation widgets.
  
  Additional properties are allowed.
  
  Hide data attributes Show data attributes object | null
  
  type string Required
  
  heading string Required
  
  items array[object] Required
  
  Recommendation item for various widget types.
  
  Hide items attributes Show items attributes object
  
  title string Required
  
  Name of the place, product, service, or item
  
  description string Required
  
  Detailed description with relevant details and benefits
  
  address string | null
  
  link string | null
  
  imageSearchQuery string | null
  
  imageUrl string | null
  
  Hide attributes Show attributes
  
  capabilityId string Required
  
  status string Required
  
  currentVersion integer Required
  
  heading string | null
  
  errorMessage string | null
  
  type string Required Discriminator
  
  Value is wearables_tracking.
  
  data object | null
  
  Widget data for trip and cart recommendation widgets.
  
  Additional properties are allowed.
  
  Hide data attributes Show data attributes object | null
  
  type string Required
  
  heading string Required
  
  items array[object] Required
  
  Recommendation item for various widget types.
  
  Hide items attributes Show items attributes object
  
  title string Required
  
  Name of the place, product, service, or item
  
  description string Required
  
  Detailed description with relevant details and benefits
  
  address string | null
  
  link string | null
  
  imageSearchQuery string | null
  
  imageUrl string | null
  
  Hide attributes Show attributes
  
  capabilityId string Required
  
  status string Required
  
  currentVersion integer Required
  
  heading string | null
  
  errorMessage string | null
  
  type string Required Discriminator
  
  Value is catalog_recommendations.
  
  data object | null
  
  Widget data for catalog_recommendations widget.
  
  Additional properties are allowed.
  
  Hide data attributes Show data attributes object | null
  
  heading string Required
  
  recommendations array[object] Required
  
  Single recommendation in catalog_recommendations widget.
  
  Hide recommendations attributes Show recommendations attributes object
  
  productId string Required
  
  product object Required
  
  Product data as returned by product_to_widget_dict().
  
  Additional properties are allowed.
  
  Hide product attributes Show product attributes object
  
  id string Required
  
  externalId string | null
  
  name string | null
  
  brand string | null
  
  price number | null
  
  originalPrice number | null
  
  currency string | null
  
  category string | null
  
  color string | null
  
  imageUrl string | null
  
  thumbnailUrl string | null
  
  linkUrl string | null
  
  inStock boolean | null
  
  reasoning string Required
  
  confidence number Required
  
  tags array[string]
  
  accepted boolean | null
  
  suggestedPrompts array[string]
  
  assistantMessage string Required
  
  Hide attributes Show attributes
  
  capabilityId string Required
  
  status string Required
  
  currentVersion integer Required
  
  heading string | null
  
  errorMessage string | null
  
  type string Required Discriminator
  
  Value is virtual_tryon.
  
  data object | null
  
  Widget data for virtual_tryon widget.
  
  Additional properties are allowed.
  
  Hide data attributes Show data attributes object | null
  
  heading string Required
  
  tryOnImageUrl string Required
  
  generatedImageResourceId string Required
  
  products array[object] Required
  
  Product data as returned by product_to_widget_dict().
  
  Hide products attributes Show products attributes object
  
  id string Required
  
  externalId string | null
  
  name string | null
  
  brand string | null
  
  price number | null
  
  originalPrice number | null
  
  currency string | null
  
  category string | null
  
  color string | null
  
  imageUrl string | null
  
  thumbnailUrl string | null
  
  linkUrl string | null
  
  inStock boolean | null
  
  wardrobeItemCount integer Required
  
  generationTimeSeconds number Required
  
  Hide attributes Show attributes
  
  capabilityId string Required
  
  status string Required
  
  currentVersion integer Required
  
  heading string | null
  
  errorMessage string | null
  
  type string Required Discriminator
  
  Value is virtual_tryon_video.
  
  data object | null
  
  Widget data for virtual_tryon_video widget.
  
  Additional properties are allowed.
  
  Hide data attributes Show data attributes object | null
  
  heading string Required
  
  videoUrl string Required
  
  thumbnailUrl string Required
  
  durationSeconds integer Required
  
  generationTimeSeconds number Required
  
  Hide attributes Show attributes
  
  capabilityId string Required
  
  status string Required
  
  currentVersion integer Required
  
  heading string | null
  
  errorMessage string | null
  
  type string Required Discriminator
  
  Value is wardrobe_recommendations.
  
  data object | null
  
  Widget data for wardrobe_recommendations widget.
  
  Additional properties are allowed.
  
  Hide data attributes Show data attributes object | null
  
  heading string Required
  
  outfitSummary string Required
  
  recommendations array[object] Required
  
  Single recommendation in wardrobe_recommendations widget.
  
  Hide recommendations attributes Show recommendations attributes object
  
  productId string Required
  
  rank integer Required
  
  reasoning string Required
  
  confidence number Required
  
  styleMatch string Required
  
  colorHarmony string | null
  
  tags array[string]
  
  product object Required
  
  Product data as returned by product_to_widget_dict().
  
  Additional properties are allowed.
  
  Hide product attributes Show product attributes object
  
  id string Required
  
  externalId string | null
  
  name string | null
  
  brand string | null
  
  price number | null
  
  originalPrice number | null
  
  currency string | null
  
  category string | null
  
  color string | null
  
  imageUrl string | null
  
  thumbnailUrl string | null
  
  linkUrl string | null
  
  inStock boolean | null
  
  assistantMessage string Required
  
  totalAnalyzed integer Required
  
  totalRecommended integer Required
  
  Hide attributes Show attributes
  
  capabilityId string Required
  
  status string Required
  
  currentVersion integer Required
  
  heading string | null
  
  errorMessage string | null
  
  type string Required Discriminator
  
  Value is recipes.
  
  data object | null
  
  Widget data for recipes widget.
  
  Additional properties are allowed.
  
  Hide data attributes Show data attributes object | null
  
  heading string Required
  
  items array[object] Required
  
  Hide items attributes Show items attributes object
  
  name string Required
  
  vibe string Required
  
  heroImageQuery string | null
  
  heroImageUrl string | null
  
  ingredients array[object] Required
  
  Hide ingredients attributes Show ingredients attributes object
  
  name string Required
  
  amount string Required
  
  inCart boolean
  
  Default value is false.
  
  imageSearchQuery string | null
  
  imageUrl string | null
  
  tools array[object] Required
  
  Hide tools attributes Show tools attributes object
  
  name string Required
  
  amount string Required
  
  inCart boolean
  
  Default value is false.
  
  imageSearchQuery string | null
  
  imageUrl string | null
  
  steps array[string] Required
  
  helperTips array[string] | null
  
  Hide attributes Show attributes
  
  capabilityId string Required
  
  status string Required
  
  currentVersion integer Required
  
  heading string | null
  
  errorMessage string | null
  
  type string Required Discriminator
  
  Value is nutrition_analysis.
  
  data object | null
  
  Widget data for nutrition_analysis widget.
  
  Additional properties are allowed.
  
  Hide data attributes Show data attributes object | null
  
  heading string Required
  
  macros array[object] Required
  
  Macro nutrient data with current value
  
  Hide macros attributes Show macros attributes object
  
  nutrient string Required
  
  Nutrient name
  
  Values are Carbs, Fat, Fiber, or Protein.
  
  current integer Required
  
  Current amount from cart (grams)
  
  unit string
  
  Unit of measurement
  
  Value is g. Default value is g.
  
  distribution object Required
  
  Percentage distribution of macronutrients
  
  Hide distribution attributes Show distribution attributes object
  
  carbs_percent number Required
  
  Percentage of total macros from carbs
  
  protein_percent number Required
  
  Percentage of total macros from protein
  
  fat_percent number Required
  
  Percentage of total macros from fat
  
  fiber_percent number Required
  
  Percentage of total macros from fiber
  
  total_macros_grams integer Required
  
  Total grams of macros (carbs + protein + fat + fiber)
  
  insight object Required
  
  LLM-generated insights about cart's nutrition profile
  
  Hide insight attributes Show insight attributes object
  
  summary string Required
  
  One sentence describing the overall macro distribution pattern
  
  key_observation string Required
  
  Most notable characteristic (e.g., low fiber, well-balanced, etc.)
  
  suggestion string Required
  
  Practical advice on what to add or adjust (1-2 sentences)
  
  balance_tip string | null
  
  items array[object] Required
  
  Product recommendation to improve nutrition balance
  
  Hide items attributes Show items attributes object
  
  name string Required
  
  Product name
  
  amount string Required
  
  Portion size with nutrient content (e.g., '~17g protein / 170g')
  
  nutrientBenefit string Required
  
  Primary nutrient this boosts
  
  Values are Carbs, Fat, Fiber, or Protein.
  
  reason string | null
  
  Hide attributes Show attributes
  
  capabilityId string Required
  
  status string Required
  
  currentVersion integer Required
  
  heading string | null
  
  errorMessage string | null
  
  type string Required Discriminator
  
  Value is weekly_meal_plan.
  
  data object | null
  
  Widget data for weekly_meal_plan widget.
  
  Additional properties are allowed.
  
  Hide data attributes Show data attributes object | null
  
  heading string Required
  
  days array[object] Required
  
  Meal plan for a single day
  
  Hide days attributes Show days attributes object
  
  dayOfWeek string Required
  
  Day of the week
  
  Values are Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, or Sunday.
  
  breakfast object Required
  
  Meal suggestion with full recipe details
  
  Hide breakfast attributes Show breakfast attributes object
  
  name string Required
  
  Meal name (e.g., 'Greek Yogurt with Berries')
  
  description string Required
  
  Brief description (1-2 sentences)
  
  prepTime string Required
  
  Preparation time (e.g., '15 minutes')
  
  servings integer Required
  
  Number of servings
  
  ingredients array[string] Required
  
  List of ingredients with amounts
  
  instructions array[string] Required
  
  Step-by-step cooking instructions
  
  lunch object Required
  
  Meal suggestion with full recipe details
  
  Hide lunch attributes Show lunch attributes object
  
  name string Required
  
  Meal name (e.g., 'Greek Yogurt with Berries')
  
  description string Required
  
  Brief description (1-2 sentences)
  
  prepTime string Required
  
  Preparation time (e.g., '15 minutes')
  
  servings integer Required
  
  Number of servings
  
  ingredients array[string] Required
  
  List of ingredients with amounts
  
  instructions array[string] Required
  
  Step-by-step cooking instructions
  
  dinner object Required
  
  Meal suggestion with full recipe details
  
  Hide dinner attributes Show dinner attributes object
  
  name string Required
  
  Meal name (e.g., 'Greek Yogurt with Berries')
  
  description string Required
  
  Brief description (1-2 sentences)
  
  prepTime string Required
  
  Preparation time (e.g., '15 minutes')
  
  servings integer Required
  
  Number of servings
  
  ingredients array[string] Required
  
  List of ingredients with amounts
  
  instructions array[string] Required
  
  Step-by-step cooking instructions
  
  beveragePairing object | null
  
  Beverage pairing suggestion (wine, cocktail, or beer)
  
  Hide beveragePairing attributes Show beveragePairing attributes object | null
  
  type string Required
  
  Type of beverage
  
  Values are wine, cocktail, or beer.
  
  name string Required
  
  Beverage name
  
  description string Required
  
  Brief description of the beverage
  
  pairingRationale string Required
  
  Why it pairs well with the meals
  
  ingredients array[string] | null
  
  instructions array[string] | null
  
  tools array[string] | null
  
  suggestedIngredients array[object]
  
  Ingredients to add to cart
  
  Suggested ingredient to complete a meal
  
  Hide suggestedIngredients attributes Show suggestedIngredients attributes object
  
  name string Required
  
  Ingredient name
  
  amount string Required
  
  Amount needed (e.g., '1 cup', '200g')
  
  reason string Required
  
  Which meal needs this ingredient
  
  Hide attributes Show attributes
  
  capabilityId string Required
  
  status string Required
  
  currentVersion integer Required
  
  heading string | null
  
  errorMessage string | null
  
  type string Required Discriminator
  
  Value is research.
  
  data object | null
  
  Widget data for research widget.
  
  Additional properties are allowed.
  
  Hide data attributes Show data attributes object | null
  
  heading string Required
  
  sections array[object] Required
  
  Single research section (one per question).
  
  Hide sections attributes Show sections attributes object
  
  question string Required
  
  answer string Required
  
  sources array[object]
  
  Citation source in a research section.
  
  Hide sources attributes Show sources attributes object
  
  title string Required
  
  url string Required
422 application/json

Validation Error
Hide response attribute Show response attribute object
- detail array[object]
  
  Hide detail attributes Show detail attributes object
  
  loc array[string | integer] Required
  
  msg string Required
  
  type string Required

POST /experiences/{experience_id}/capabilities

curl \
 --request POST 'http://api.example.com/experiences/{experience_id}/capabilities' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"context":{"cart":{"type":"grocery","products":[{"productId":"string","name":"string","brand":"string","price":42.0,"category":"string","quantity":1,"size":"string","unit":"string","barcode":"string","organic":false,"glutenFree":false}]},"trip":{"flight":{"departureAirport":"string","arrivalAirport":"string","departureTimestamp":42,"arrivalTimestamp":42,"numTravelers":42,"seatClass":"economy"},"cruise":{"departurePort":"string","arrivalPort":"string","departureTimestamp":42,"arrivalTimestamp":42,"numTravelers":42}},"topic":{"topic":"string","questions":["string"]},"history":{"orders":[{"productId":"string","name":"string","brand":"string","category":"string","color":"string","purchasedAt":"string"}]}},"capabilities":[{"type":"catalog_recommendations","config":{"allowedSources":["string"],"blockedSources":["string"],"catalogSlug":"string","maxResults":6,"budgetMax":42.0}}]}'

Request examples

{
  "context": {
    "cart": {
      "type": "grocery",
      "products": [
        {
          "productId": "string",
          "name": "string",
          "brand": "string",
          "price": 42.0,
          "category": "string",
          "quantity": 1,
          "size": "string",
          "unit": "string",
          "barcode": "string",
          "organic": false,
          "glutenFree": false
        }
      ]
    },
    "trip": {
      "flight": {
        "departureAirport": "string",
        "arrivalAirport": "string",
        "departureTimestamp": 42,
        "arrivalTimestamp": 42,
        "numTravelers": 42,
        "seatClass": "economy"
      },
      "cruise": {
        "departurePort": "string",
        "arrivalPort": "string",
        "departureTimestamp": 42,
        "arrivalTimestamp": 42,
        "numTravelers": 42
      }
    },
    "topic": {
      "topic": "string",
      "questions": [
        "string"
      ]
    },
    "history": {
      "orders": [
        {
          "productId": "string",
          "name": "string",
          "brand": "string",
          "category": "string",
          "color": "string",
          "purchasedAt": "string"
        }
      ]
    }
  },
  "capabilities": [
    {
      "type": "catalog_recommendations",
      "config": {
        "allowedSources": [
          "string"
        ],
        "blockedSources": [
          "string"
        ],
        "catalogSlug": "string",
        "maxResults": 6,
        "budgetMax": 42.0
      }
    }
  ]
}

Response examples (200)

{
  "experienceId": "string",
  "status": "string",
  "widgets": [
    {
      "capabilityId": "string",
      "status": "string",
      "currentVersion": 42,
      "heading": "string",
      "errorMessage": "string",
      "type": "restaurants",
      "data": {
        "type": "string",
        "heading": "string",
        "items": [
          {
            "title": "string",
            "description": "string",
            "address": "string",
            "link": "string",
            "imageSearchQuery": "string",
            "imageUrl": "string"
          }
        ]
      }
    }
  ]
}

Response examples (422)

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}