Surfaces

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 Key	Display Name	Max Title	Max Description	Tone
`google_shopping`	Google Shopping	150 chars	5000 chars	SEO-optimized
`openai_commerce`	OpenAI Commerce	200 chars	2000 chars	Conversational
`mobile_pdp`	Mobile Product Page	65 chars	300 chars	Concise
`desktop_pdp`	Desktop Product Page	200 chars	2000 chars	Detailed
`agent_response`	AI Agent Response	100 chars	500 chars	Natural 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:

Cache hit?  → Return cached resolved product (< 5ms)
Null marker? → No override exists → Return universal content
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.

Getting Started

Core Concepts

Guides

What are Surfaces?

System Surfaces

Custom Surfaces

How Surface Resolution Works

Surface Overrides

Surfaces Across Channels

Canal 1 — Feed API

Canal 2 — Search API

Canal 3 — MCP Tools

​What are Surfaces?

​System Surfaces

​Custom Surfaces

​How Surface Resolution Works

​Surface Overrides

​Surfaces Across Channels

​Canal 1 — Feed API

​Canal 2 — Search API

​Canal 3 — MCP Tools

What are Surfaces?

System Surfaces

Custom Surfaces

How Surface Resolution Works

Surface Overrides

Surfaces Across Channels

Canal 1 — Feed API

Canal 2 — Search API

Canal 3 — MCP Tools