> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alana.shopping/llms.txt
> Use this file to discover all available pages before exploring further.

# Surfaces

> Adapt product content for different distribution channels and platforms automatically.

## 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](/en/api-reference/surfaces/list-surfaces).

## 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:

```bash theme={null}
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:

```bash theme={null}
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](/en/api-reference/mcp/commerce-tools) for the full tool reference.