Skip to main content

​
What are Surfaces?

A Surface is a named display context that defines how product content should be adapted for a specific distribution channel or platform. Each surface has constraints — max title length, tone of voice, format hints — that guide the AI when generating content. Without surfaces, the Canvas generates “universal” content: a single version of each product’s title, description, and attributes that serves as the default across all channels. With surfaces, you can generate channel-specific versions that are optimized for each platform’s requirements and audience expectations.

​
System Surfaces

Alana provides five pre-configured system surfaces that cover the most common distribution channels. System surfaces cannot be deleted, but you can generate overrides for any product on any of them.
Surface KeyDisplay NameMax TitleMax DescriptionTone
google_shoppingGoogle Shopping150 chars5000 charsSEO-optimized
openai_commerceOpenAI Commerce200 chars2000 charsConversational
mobile_pdpMobile Product Page65 chars300 charsConcise
desktop_pdpDesktop Product Page200 chars2000 charsDetailed
agent_responseAI Agent Response100 chars500 charsNatural language

​
Custom Surfaces

Workspaces can create custom surfaces for any display context they need. A custom surface has a unique surface_key (lowercase letters, digits, and underscores), a display name, and optional constraints. Examples of custom surfaces:
  • tiktok_shop — short-form descriptions optimized for TikTok’s buying intent
  • trade_show_kiosk — large-display format with bold headlines
  • whatsapp_catalog — catalog API format for WhatsApp Business
  • b2b_wholesale — technical specifications in a formal tone
Custom surfaces are created and managed in Settings > Surfaces, or via the Surfaces API.

​
How Surface Resolution Works

When a channel requests product content with a surface context, Alana resolves the content through a three-tier cache: 
1. Cache hit?  → Return cached resolved product (< 5ms)
2. Null marker? → No override exists → Return universal content
3. DB lookup   → Fetch override → Deep merge → Cache and return
The resolution logic: 
universal = catalog_products[product_id]      // always present
overrides = product_surfaces[product_id, surface_key]  // may not exist
resolved  = deepMerge(universal, overrides)   // surface wins where present
If no surface override exists for a product, the universal content is returned unchanged. This means surfaces are always backward-compatible — existing API consumers that don’t pass a surface key receive the same universal content as before.

​
Surface Overrides

A surface override is a partial set of product fields stored per-product, per-surface in the product_surfaces table. Overrides are generated by:
  • Canvas: Select a surface before generating content; the AI applies the surface constraints automatically
  • API: PUT a partial product object to /api/workspace/{id}/products/{pid}/surfaces/{key}
  • Bulk: Generate overrides for multiple products at once via the Batch API
Only the fields present in the override replace the universal values. Fields not in the override continue to come from the universal product record.

​
Surfaces Across Channels

Each channel resolves surfaces differently:

​
Canal 1 — Feed API

The platform determines the surface implicitly. There is no surface query parameter — the feed endpoint selects the surface based on the platform: 
GET /api/mcp/feed/google_shopping?workspace_id={id}
# → surface_key = "google_shopping" applied automatically
Platforms without a matching surface key (e.g., vtex, shopify, nuvemshop) receive universal content.

​
Canal 2 — Search API

Pass the surface query parameter to receive surface-adapted content: 
GET /api/mcp/search?workspace_id={id}&surface=mobile_pdp&q=shoes
# → Returns titles ≤ 65 chars, descriptions ≤ 300 chars
Omitting surface returns universal content.

​
Canal 3 — MCP Tools

AI agents can request surface-resolved content using the surface parameter in tool calls, or use the dedicated surface tools:
  • list_surfaces — enumerate available surfaces for a workspace
  • get_surface_product — fetch a product with a specific surface applied
See MCP Tools for the full tool reference.
Last modified on March 19, 2026