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

# Surface Content Generation

> Generate and manage surface-adapted product content using the API and Canvas.

## Overview

Surface content generation allows you to create channel-specific versions of product content that are automatically optimized for each platform's requirements. Instead of manually editing titles for Google Shopping character limits or rewriting descriptions for mobile screens, the AI adapts the content based on surface constraints you define.

## Prerequisites

* A workspace with at least one catalog and products
* API key with `write:surfaces` scope (for API usage)
* At least one surface available (system surfaces are always available)

## Generate via Canvas

The simplest way to generate surface-adapted content is through the Canvas UI:

<Steps>
  <Step title="Open Canvas for a product">
    Navigate to your catalog, find the product, and open its Canvas.
  </Step>

  <Step title="Select a surface">
    Use the surface selector dropdown at the top of the Canvas. Choose from system surfaces (Google Shopping, OpenAI Commerce, etc.) or any custom surfaces your workspace has configured.
  </Step>

  <Step title="Generate content">
    Click any Canvas action (Text, SEO, etc.). The AI applies the surface constraints automatically — titles will respect the max length, tone will match the surface requirements, and format hints guide the output.
  </Step>

  <Step title="Review and commit">
    Review the generated content in the surface preview. When satisfied, commit the content. It is stored as a surface override for this product.
  </Step>

  <Step title="Content is now available">
    The override is immediately available to all channels. The next Canal 1 feed sync, Canal 2 search result, or Canal 3 tool call for this product + surface will return the adapted content.
  </Step>
</Steps>

## Generate via API

### Step 1: List available surfaces

```bash theme={null}
curl "https://app.alana.shopping/api/workspace/{workspaceId}/surfaces" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "surfaces": [
    {
      "id": "...",
      "surface_key": "google_shopping",
      "display_name": "Google Shopping",
      "is_system": true,
      "constraints": {
        "max_title_length": 150,
        "max_description_length": 5000,
        "tone": "seo-optimized"
      }
    }
  ]
}
```

### Step 2: Generate content with surface constraints

Trigger Canvas generation with a `surfaceKey` parameter:

```bash theme={null}
curl -X POST "https://app.alana.shopping/api/ai/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "BRAND_ID",
    "productId": "PRODUCT_ID",
    "type": "text",
    "surfaceKey": "google_shopping"
  }'
```

### Step 3: Read the resolved product

```bash theme={null}
curl "https://app.alana.shopping/api/workspace/{workspaceId}/products/{productId}/surfaces/google_shopping" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "product": {
    "productId": "...",
    "surface_key": "google_shopping",
    "resolved": {
      "title": "Organic Linen Blazer - Navy | Sustainable Premium",
      "description": "Premium organic linen blazer in navy..."
    },
    "overrides": {
      "title": "Organic Linen Blazer - Navy | Sustainable Premium",
      "description": "Premium organic linen blazer in navy..."
    },
    "cached": true
  }
}
```

### Step 4: Set overrides manually (optional)

Skip AI generation and set overrides directly:

```bash theme={null}
curl -X PUT "https://app.alana.shopping/api/workspace/{workspaceId}/products/{productId}/surfaces/google_shopping" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "overrides": {
      "title": "My custom Google Shopping title",
      "description": "My custom description for Google"
    }
  }'
```

## Serve via Channels

### Canal 1 — Feed API

Surface overrides are applied automatically when the platform maps to a surface:

```bash theme={null}
GET https://app.alana.shopping/api/mcp/feed/google_shopping?workspace_id={workspaceId}&catalog_id={catalogId}
```

Products with `google_shopping` overrides will return the adapted title and description. Products without overrides return the universal content.

### Canal 2 — Search API

```bash theme={null}
GET https://app.alana.shopping/api/mcp/search?workspace_id={workspaceId}&surface=google_shopping&q=blazer
```

All products in the result set will have surface resolution applied. The `surface` parameter accepts any valid surface key.

### Canal 3 — MCP Tools

```json theme={null}
{
  "tool": "get_product",
  "params": {
    "product_id": "PRODUCT_ID",
    "workspace_id": "WORKSPACE_ID",
    "surface": "agent_response"
  }
}
```

Or use the dedicated surface tools:

```json theme={null}
{
  "tool": "list_surfaces",
  "params": { "workspace_id": "WORKSPACE_ID" }
}
```

```json theme={null}
{
  "tool": "get_surface_product",
  "params": {
    "product_id": "PRODUCT_ID",
    "workspace_id": "WORKSPACE_ID",
    "surface_key": "agent_response"
  }
}
```

## Create Custom Surfaces

```bash theme={null}
curl -X POST "https://app.alana.shopping/api/workspace/{workspaceId}/surfaces" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "surface_key": "tiktok_shop",
    "display_name": "TikTok Shop",
    "constraints": {
      "max_title_length": 34,
      "max_description_length": 200,
      "tone": "casual",
      "format_hints": "Short punchy sentences. Use emojis sparingly. Focus on trend appeal."
    }
  }'
```

The `surface_key` must match `^[a-z][a-z0-9_]{1,48}[a-z0-9]$`. It cannot be changed after creation.

## Delete a Surface Override

To revert a product back to universal content for a surface:

```bash theme={null}
curl -X DELETE "https://app.alana.shopping/api/workspace/{workspaceId}/products/{productId}/surfaces/google_shopping" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Best Practices

* **Start with system surfaces** for standard platforms (Google Shopping, OpenAI Commerce). They are pre-configured with optimal constraints.
* **Use Canvas for generation** rather than setting overrides manually — the AI produces better results when it understands the surface constraints during generation.
* **Create custom surfaces sparingly** — each new surface adds content generation and storage overhead per product. Only create surfaces you'll actively generate overrides for.
* **Review before publishing** — generated surface content should be reviewed, especially for tone and accuracy, before relying on it in production channels.
* **Cache warm-up** — after creating a surface or updating constraints, the cache warmer runs automatically for the top 100 products. New products are warmed on first access.